` of the static page | | `failOnEmpty` | `false` | fail the build if zero routes rendered | | `failOnSkipped` | `false` | fail the build if **any** route could not be bundled — turn it on once your bundled set is stable, so a route dropping out stops being a silent regression | | `static` (config `<staticOnly>`) | `false` | declare the bundle **100 % static**: runs the [static-safety report](/deploy/static-ui/#the-static-safety-report) and **fails the build** if any route still needs a server | | `specsOnly` | `false` | ship each definition-only route the browser can expand as its **raw definition** instead of pre-rendering it ([specs mode](/deploy/static-ui/#two-ways-to-build-it)) | ### Knowing which bundle you are looking at The manifest carries a `structureHash`: a stable identity of **what the bundle contains**, independent of when it was built. `generatedAt` cannot answer "is this the same bundle?" — it differs on every build, and a stale bundle looks as fresh as any other. That matters because a bundle is derivation frozen in time. Deployed to a CDN it can outlive the model it came from, and in a hybrid deploy a client can be answering loads from build N while posting actions to a backend at N+1, with nothing anywhere saying so. Comparing hashes is what makes the bundle a **cache** rather than a fork — same hash, same screens — and gives a deploy check something to assert. The hash ignores entry order (route discovery walks beans and indexes, so the order is not stable between builds) and changes when a route stops being bundled, which is exactly the regression that otherwise leaves only a line in a build log. ## Serving the bundle at runtime (no build step) You don't have to run the Maven goal: a running Mateu app exposes the same bundle live at ``` GET /mateu/v3/bundle ``` which returns the identical `manifest.json`, rendered from the app's real bean graph — so it has **full fidelity** (services/DB available, no skipped service-backed loads) and needs no build. Add `?params=true` to also include [`:param` route templates](#param-route-templates). Two uses: - **Point a static shell at it** — host a small `index.html` + the renderer assets on a CDN and set `<mateu-ui bundleUrl="https://your-app/mateu/v3/bundle">`. The shell fetches the bundle over CORS (the endpoint sends the header) and answers loads from it — instant first paint, backend still there for actions. (Same-origin `bundleUrl="/mateu/v3/bundle"` works too.) - **Snapshot it** — `curl https://your-app/mateu/v3/bundle > manifest.json` to produce the bundle in CI without the Maven goal. The result is computed once and cached (structure is stable within a deployment). The endpoint ships in **every server adapter** — Spring MVC, Spring WebFlux, Micronaut, Quarkus and Helidon MP — and discovers routes from the live `RouteResolver` beans, so it works whether your `@UI` classes live in the app module or in a separate UI module. **Cross-origin note:** same-origin serving needs no CORS at all. To read the endpoint from another origin, list that origin in `mateu.cors.allowed-origins` — the same opt-in allow-list, and the same behaviour, on every adapter (see [Configuration properties](/java-create-your-project/configuration/#cross-origin-access-cors)). ## `:param` route templates A parameterised route (`/orders/:id`) can't be pre-rendered for one specific id, but if its **structure is param-independent** (a detail screen whose data is fetched client-side), it can be bundled once as a **template**: :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: - Enable it: `mvn -Pbundle package -Dmateu.bundle.skipParamRoutes=false`, or hit the runtime endpoint with `GET /mateu/v3/bundle?params=true`. - The exporter renders the route once with a placeholder param and stores the entry with a regex (`^orders/([^/]+)$`) and the param names. - At runtime the client matches a concrete path (`/orders/42`) against the template, extracts the params and **injects them into the screen's state** (`state.id = "42"`). Any `${state.id}` in a client-side data URL (`@RestOptions`/`@RestData`) then resolves to the real value — so a per-id detail screen works served from a static host with **no backend**. ```java @UI("/item/:id") @Title("Item ${state.id}") public class Item { private String id; // receives the real id from the path at runtime @RestOptions(url = "https://api.example.com/posts?userId=${state.id}", valuePath = "id", labelPath = "title") private String relatedPost; // options fetched client-side for id=42 } ``` A view whose load *hard-fails* on the placeholder (e.g. parses it as a number and reads a DB) is skipped, exactly like a static view that needs a live backend. See `demo/demo-static-bundle` (`/item/:id`). ## What works without a backend - **Presentational and form screens** — any declared `@UI`/`routes.yaml` route whose initial render is structural (fields, sections, tabs, layouts). - **Live data via external endpoints** — `@RestOptions`/`@RestListing`/`@RestData`/`@RestAction` fetch directly from your REST APIs client-side, so a bundled screen shows real data with no Mateu backend (use `proxy = true` needs a backend; the direct mode is what works statically). ## What still needs a backend - **Server actions** — a button/toolbar/save whose action is a Java method (`actionId ≠ ""` with no `restAction`) posts to the server. Without one it degrades with a clear "request failed" message. A **`@RestAction`** (or a YAML `restAction`) is different: the browser makes the call itself, so a confirmed delete or a save against your API works with no backend — see the [100 % static UI guide](/deploy/static-ui/). `staticOnly` turns any leftover server action into a build error. - **Parameterised routes** (`/orders/:id`) — skipped by default; can be bundled as [templates](#param-route-templates) when the structure is param-independent (data fetched client-side). A view that loads its entity server-side by id still needs a backend. - **Service-backed loads** — a ViewModel whose initial load needs a live DB / a bean the build can't construct is skipped at export time (logged) and stays backend-served. - **Screens gated on identity** — a route whose class, field or method declares `@EyesOnly` is **skipped on purpose** and stays backend-served. A bundle is one file served to everyone, and export runs headless: with no `Authorization` header the authorizer denies restricted content, so nothing leaks — it fails closed. What would leak instead is *correctness*: the baked variant is the **denied** one, and an authorised user hitting a static host has no server left to re-render the version they are entitled to. The skip reason names the member, so the build log says which one. `@Audience` is deliberately **not** treated this way: it is a UX projection, not access control, so with no audience selected the export renders the full, unprojected view — correct for everyone, merely not personalised. A **hybrid** deploy is the sweet spot: ship the bundle for instant, backend-free first paint, and point `baseUrl` at a real backend so actions and unbundled/param routes still work — the client uses the bundle for the loads it has and falls through to the backend for everything else. ## App shells: two loads per route Under a mount whose root is an **app shell** (`@UI("")` with a menu, or a YAML `type: AppShell`), a route has two loads: the **fresh** one (a deep link or a reload) answers the *shell*, aimed at the route; the shell then asks for its **content** slot, and that is the route's own screen. The exporter ships both — `json` and `contentJson` on the entry — and the client picks by the request's consumed route. (Shipping only the first is what made a bundled deep link "render HOME", #557.) ## Renderers - **Vaadin** and every renderer built on the shared `libs/mateu` client get bundle mode for free — set `<mateu-ui bundleUrl="…">` (the `mateu-bundle:bundle` goal stamps it into the generated `index.html`). - **Redwood/VB** has its own transport (it shares no code with the web renderers), so bundle mode is ported there too: set the app constant **`mateuBundleUrl`** (empty = off) to a `manifest.json` URL or the runtime `…/mateu/v3/bundle` endpoint. Route loads are answered from the bundle; in a hybrid deploy the menu/shell still comes from the backend, and if the backend is absent the shell falls back to the bundled root route. Contract-tested in `apps/redwood/poc/test.mjs`. It does **not** yet read an entry's `contentJson`, the raw `definitions` or the source catalogue — under an app shell, static Redwood is structure-only for now. ## Notes - The manifest carries only screen **structure** (never business data), so nothing stale is baked in; data is always fetched live. - The manifest also carries the mount's [route registry](/concepts/routes-and-mounts/) when the app declares one — a statically deployed mount has no server left to ask what a URL means, so the renderer resolves routes and their parameters from shipped data. Only the authored half travels: the annotation-derived half is route→class, and a class is what a bundle with no backend cannot use. Routes that exist only in `routes.yaml` are exported too, **including those with no view model** — a definition that declares no `modelView` renders as a bare layout through the ordinary sync path, so it is pre-rendered like any other route. --- # A 100 % static UI — no backend of your own URL: https://mateu.io/deploy/static-ui/ > Serve a Mateu UI as plain files — definitions read by the browser, data straight from a REST API — the way a cloud console like OCI's is built. How to author it, build it, host it, and what cannot be static yet. **Status:** ✅ Works today for listings, record pages, linked child listings and REST writes, on the Vaadin and the Redwood renderer (Redwood bundles are always pre-rendered — see below). Proven end to end by `demo/demo-static-vcn` and its e2e. Gaps are listed [at the end](#what-is-not-possible-statically-yet). A Mateu UI does not need a Mateu server. The model can travel to the browser as data, and every call the screens make can go **straight from the browser to your REST API** — so the whole UI is a folder of files on a CDN. This is how OCI's console (MAUI) works: page definitions the browser reads, data from the cloud APIs, no backend-for-frontend. ``` static host (CDN, S3, nginx…) your REST API (CORS on) ┌───────────────────────────┐ ┌──────────────────────┐ │ index.html assets/ │ GET /vcns │ │ │ manifest.json ────────────┼───────────────▶ │ /api/vcns │ │ (screens + sources) │ DELETE /vcns/7│ /api/vcns/:id … │ └───────────────────────────┘ └──────────────────────┘ no Mateu backend anywhere ``` ## What a static screen is made of Everything a screen does after it is painted has to be **declared on the wire**, because there is no JVM left to run a method body: | The screen needs to… | Declare it as | Java | YAML | |---|---|---|---| | list rows from the API | a rows source | `@RestListing(source = "vcns")` | `rowsSource: { ref: vcns }` | | filter, search and page them | — (the renderer does it over the fetched rows) | `Filterable<Filters>`, `Searchable` | `filters:`, `searchable: true` | | open a record by URL | a row route | `@RestListing(rowRoute = "vcns/${row.id}")` | `rowRoute: vcns/${row.id}` | | load a record by `:id` | a data source run on load | `@RestData(source = "vcn")` | the route's `data: vcn` | | show a lifecycle badge | a status column | `@Status` on the row field | `dataType: status` | | navigate | a button whose actionable is a `RouteLink` | `Button…actionable(new RouteLink(…))` | `actionable: { type: RouteLink, route: … }` | | write (delete, save…) | a REST action | `@RestAction(source = "vcn-delete", successRoute = "vcns")` | `actions: [{ id: delete, restAction: { … } }]` | | confirm first | the action's confirmation | `@Action(confirmationRequired = true, …)` | `confirmationRequired: true` | The endpoints themselves are named **once**, in the REST source catalogue — `@RestSource` on the app class or `specs/ui/sources.yaml` — and every surface references them by name. The catalogue travels in `manifest.json`, so pointing a deployed site at another environment is an edit of that table, not a rebuild. A status column over a plain lifecycle word (`"AVAILABLE"`) is painted as a badge with the usual meaning of the word (available/active → success, provisioning/updating → warning, failed/terminated → error). Inner routes are data: `@UI("")` declares the mount (the app shell); `specs/ui/routes.yaml` binds the routes inside it — to a Java view model (`viewModel:`) or to a definition only (`layout:`; the older key `definition:` is a deprecated alias). ## Two ways to build it **From Java** — the `bundle` goal (`mvn mateu-bundle:bundle`) boots your classes at build time and **pre-renders** every route into `manifest.json` (`:id` routes as templates, filled in the browser): ```xml <plugin> <groupId>io.mateu</groupId> <artifactId>mateu-bundle-maven-plugin</artifactId> <configuration> <skipParamRoutes>false</skipParamRoutes>  <staticOnly>true</staticOnly>  </configuration> <executions><execution><goals><goal>bundle</goal></goals></execution></executions> </plugin> ``` If your `@UI` classes live in the app module itself, add `mateu-annotation-processor-indexer` next to your framework's annotation processor: it writes the class index the build-time catalogue (`@RestSource`) and exporter read. **From YAML** — add `<specsOnly>true</specsOnly>`: every definition-only route whose type the browser can expand (`AppShell`, `Listing`/`Crudl`, `Form`, the layouts, `Card`) ships as its **raw definition**, and the client-side expander turns it into the wire at runtime. Nothing is pre-rendered; edit a definition in `manifest.json`, refresh, see it. Either way the output is `target/mateu-bundle/`: `index.html`, `manifest.json`, the renderer's static app (`assets/` for Vaadin, `_redwood/` for Redwood) and a `_redirects` SPA fallback. ## Choosing the renderer The bundle ships the **project's renderer**, the one `specs/ui/project.yaml` names (see [project settings](/define/yaml/project-settings)). The goal chooses it in this order: 1. `<renderer>vaadin|redwood</renderer>` (`-Dmateu.bundle.renderer`), when set; 2. otherwise `renderer:` in `project.yaml`; 3. otherwise the renderer jar on the app's classpath; otherwise Vaadin. The renderer's static app is copied straight out of its jar on the app's classpath (`io.mateu:mateu-vaadin` or `io.mateu:mateu-redwood`; `<assetsFrom>` still overrides it with a folder). When both jars are present, the one that matches is used. When the chosen one is missing, the build fails and names the artifact to add. **A Redwood bundle** is the Oracle Visual Builder app of `io.mateu:mateu-redwood` (its `_redwood/` folder) booting from `manifest.json` with no backend. The menu, routes and deep links work through the `_redirects` fallback, and a route under an app shell paints its own screen inside the shell. Things to know: - **Everything is pre-rendered.** The Redwood renderer has no client-side expander, so `<specsOnly>` is ignored for it, with a warning, and every route is rendered at build time. - **Oracle's CDN.** JET, the Spectra components and the Visual Builder runtime load from `static.oracle.com` at run time, as in every Redwood app. - **Serve it at the root of its host.** Its assets are addressed from `/_redwood/`. **From the visual editor**, **Export** writes a `manifest.json` for the project's renderer. For a Redwood project it adds the pre-rendered entries the Redwood renderer reads. They are expanded in the browser with the same runtime as Play. Put the manifest next to the Redwood static app, and name it from its `index.html` with an **absolute** path — `<mateu-ui bundleUrl="/manifest.json">` (or `<base path>/manifest.json`): a deep link reached through the SPA fallback keeps the document base at that deep path, so a relative `./manifest.json` would 404 there. Letting `mateu-bundle:bundle` write the whole site does that for you. ## The static-safety report A pre-rendered page is a snapshot, and nothing used to tell you which of your screens still needed a server — the build passed and the first click on the CDN said "request failed". With `staticOnly` (`-Dmateu.bundle.static=true`) the goal checks every route and **fails the build**, naming the route and the reason, if it finds: - a route that could not be bundled at all (it would be backend-served, and there is no backend); - `@EyesOnly` — a screen that depends on who asks cannot be one file for everyone; - a Java action method (`@Button`, `@Toolbar`, `@ListToolbarButton`, …) without `@RestAction`, or an `ActionHandler`; - rows from `Listing.search()` (a `Listing` with no `@RestListing`) or from a `CrudStore`; - a trigger (on load, on success…) that runs an action the browser cannot complete; - a source fetched through the server proxy (`proxy: true`), or a **direct** source that uses `${secret.…}` — the browser has no secret scope, and a secret in a static file is not a secret; - in a definition, a button with neither a route nor a declared `restAction`. ``` mateu-bundle: the bundle is declared static (staticOnly) but 1 thing(s) still need a server: /vcns/:id — VcnDetail.archive() is a Java action method (add @RestAction to run it in the browser) ``` Without `staticOnly` the bundle is a **hybrid**: whatever it cannot answer falls through to the backend at `baseUrl`. That is a legitimate deployment too. ## Hosting - **Any static host.** Serve the folder with an **SPA fallback** — every path that is not a file gets `index.html` (Netlify reads the shipped `_redirects`; S3/CloudFront: an error document; nginx: `try_files $uri /index.html`). Deep links (`/vcns/7`) then boot the app, which resolves the route from the manifest. - **CORS.** Direct calls come from the browser, so every API must allow the site's origin (`Access-Control-Allow-Origin`, and `-Methods`/`-Headers` for writes and custom headers). The zero-code alternative is a **same-origin reverse proxy** at the CDN (route `/api/*` to the API) — then the sources use relative URLs and there is no CORS at all. - **Re-pointing** an environment is an edit of `sources` in `manifest.json`. ## Auth, and what it can and cannot do - **Who the user is** comes from your identity provider in the browser. Register a provider with `registerExternalAuthProvider` (libs/mateu) to add an `Authorization` header to the direct calls; the API validates the token. The provider is asked for every direct call, so it must decide by `url` and answer `{}` for an endpoint the token is not for (see [client-side auth](/java-ui-definition/annotations/rest-options/#client-side-auth-for-the-direct-path-registerexternalauthprovider)). - **Authorization lives in the API.** UI gating in a static bundle is advisory — the files are public, and a hidden button is not a permission. `@EyesOnly` screens are refused by the static check on purpose (a bundle also reveals structure). - **YAML access rules** (`access:`, `eyesOnly:`, `readOnlyUnless:`, `disabledUnless:`) are refused by the static check the same way, and a hybrid bundle keeps those routes backend-served — see [Permissions in YAML](/define/yaml/permissions/#static-bundles-and-play). - **Translations work statically**: the catalogue travels in `manifest.json` and the browser resolves `${i18n.…}` for the visitor's language — see [Translations in YAML](/define/yaml/translations/#static-bundles-and-play). - **No secrets in the bundle.** An API key belongs on a server: use the proxy (a hybrid deploy) or a token the user's session obtains. ## Run the reference demo ```bash cd demo/demo-static-vcn ./run-static.sh # external API :8790, Java site :8791, YAML site :8792 cd ../../e2e && npx playwright test --project static-vcn-java --project static-vcn-yaml --workers=1 ``` The e2e fails if anything calls `/mateu/v3/**`: there is no Mateu backend in the picture. ## What is not possible statically yet The demo covers the read-navigate-delete loop of a console. What MAUI does beyond it, and Mateu does not yet do without a server, is on the roadmap: - **Expression scopes** (S1) — `${…}` runs in Mateu's own sandboxed evaluator (no `new Function`, so a CSP without `unsafe-eval` is fine — see [Security](/java-user-manual/advanced/security/)); it sees `state`, `data`, `appState`, `appData` and `component`, but no `route`/`flags` scopes. - **Named data slots and `bind`** (S1) — a source's result goes into the page state; there is no `data.<name>` with loading/error status, and nothing re-fetches when a dependency changes. - **A declared status mapping** (S1) — `@Status(mappings)` is applied on the server only; REST rows use the built-in word table above. - **Action chains** (S2) — `onSuccess`/`onError` steps, `If`/`Set`/`Refresh(target)`, overlays opened with arguments, polling (`OnTimer`). - **Validators beyond `required` in the expander** (S3) — the client-side expander gives editable fields their required check (the same condition and message the server emits), but `min`/`max`/ `pattern` validators and `layoutDelta` are pre-rendered from Java only. Routed tabs (P1) too. - **Redwood raw definitions** (S4) — Redwood's bundle mode reads pre-rendered entries only (with `contentJson` under an app shell), so `specsOnly` does not apply to it. It does read the source catalogue and translations from the manifest and runs `restAction`s in the browser. - **Auth** (S4) — no built-in OIDC/PKCE client; bring your own provider. --- # UX Patterns URL: https://mateu.io/ux-patterns/ > Design patterns for productive business applications in Mateu. Backoffice applications are work tools. Their quality is measured not by visual flair but by productivity, safety, and the reduction of cognitive effort. Users spend hours inside these systems — every unnecessary click, every lost filter, every context switch carries a real operational cost. Mateu's thesis is that good business UX is regular enough to be codified once, on the backend, and applied consistently without writing frontend code. This section documents the patterns Mateu supports and how to express each one. New here? Start with the [UX guide](/ux/): it explains the structure of an app, the six [page types](/ux/page-types/) and the [component catalogue](/ux/components/) top-down, and links back to these pattern pages for the details. This catalogue is the reference: consult it, don't read it front to back. ## Principles Seven principles drive every pattern in this catalogue. Each exists to eliminate a concrete cost. | # | Principle | What it prevents | |---|-----------|-----------------| | 01 | **Preserve context** | Users should never lose their orientation or mental state. Leaving a screen to come back is the most expensive form of context loss. | | 02 | **Minimize navigation** | Fewer screens and fewer jumps equal more productivity. Composing beats navigating. | | 03 | **Keyboard-first** | Power users live on the keyboard. If a frequent task requires a mouse, it is badly designed. | | 04 | **Workflow over screens** | The unit of design is the task, not the screen. Design to complete work, not to display an entity. | | 05 | **Progressive complexity** | Show complexity only when it adds value. Advanced features are revealed, not imposed. | | 06 | **Recoverability** | Every error must be correctable. Confirm destructive actions, undo reversible ones, never lose work in progress. | | 07 | **Consistency** | Patterns repeat predictably. What a user learns on one screen works on all. | How these principles are checked — heuristic reviews, task walkthroughs, synthetic users, task metrics and accessibility probes on every renderer — is described in [How Mateu's UX is evaluated](/ux-patterns/how-ux-is-evaluated/). ## Pattern catalogue Looking for **full-page templates** (record overview, collection detail, guided process, create and edit in a drawer…)? They have their own map: [Page templates](./page-templates). | Pattern | Status | Key primitive | |---------|--------|---------------| | [Navigation & Menus](./navigation) | ✅ Implemented | `@App(AppVariant.*)`, `⌘K` command palette | | [Split View](./split-view) | ✅ Implemented | `@SplitCrud` | | [Tree CRUD](./tree-crud) | ✅ Implemented | `gridLayout() = GridLayout.tree`, `@SplitCrud` | | [Filters & Listing](./filters-and-listing) | ✅ Implemented | `AutoCrud` / `Listing`, `@Filterable`, `ColumnActionGroup` | | [Bulk actions](./bulk-actions) | ✅ Implemented | `@ListToolbarButton` + typed `List<Row>` selection | | [Saved views](./saved-views) | ✅ Implemented | Smart search bar bookmark — named condition sets, default view | | [Totals & row grouping](./aggregates) | ✅ Implemented | `@Aggregate(sum/avg/…)` footer + `@GroupBy` subtotal rows | | [Column chooser](./column-chooser) | ✅ Implemented | Show/hide/reorder columns per user, per listing | | [Guided import](./guided-import) | ✅ Implemented | `ImportWizard<Row>` — upload → map columns → validate → import | | [Concurrent edit conflicts](./optimistic-locking) | ✅ Implemented | `@Version` — conflict dialog: reload / overwrite | | [Notification inbox](./notification-inbox) | ✅ Implemented | `NotificationsSupplier` — header bell, unread count, mark-as-read | | [Undo](./undo) | ✅ Implemented | `Message.undoable(...)` — toast with an Undo button | | [Session expiry](./session-expiry) | ✅ Implemented | `onSessionExpired` — re-auth + retry, work intact | | [Audit version diff](./audit-diff) | ✅ Implemented | History grouped by save moment — old → new per field | | [Global entity search](./global-search) | ✅ Implemented | `GlobalSearchSupplier` — ⌘K searches data, grouped by category | | [Planning board](./planning-board) | ✅ Implemented | `PlanningBoard` — resources × days tape chart, drag to move | | [Wizard](./wizard) | ✅ Implemented | `@WizardCompletionAction`, `@WizardProgress(BAR/STEPS/RAIL)` | | [CRUD editing in a drawer](./drawer#crud-editing-in-a-drawer-editindrawer) | ✅ Implemented | `editInDrawer()` — create/edit slides over the listing | | [Collection detail](./collection-detail) | ✅ Implemented | `CollectionDetail<Row>` — searchable list + in-place detail | | [General overview](./general-overview) | ✅ Implemented | `GeneralOverview<Row>` — record context switcher + overview | | [Entity Picker](./entity-picker) | ✅ Implemented | `@Lookup`, `@Searchable` | | [Workspace](./workspace) | Composition | `@MasterDetail`, `@Tab`, `@FoldedLayout` | | [Task-centric page](./task-centric) | Composition | `@Action`, `@Button(buttonStyle = primary)` | | [Long-running jobs](./long-running-jobs) | ✅ Implemented | `@Action(background, sse)`, `@Trigger` | | [Autosave](./autosave) | ✅ Implemented | `@AutoSave` | | [Keyboard Shortcuts](./keyboard-shortcuts) | ✅ Implemented | `@Action(shortcut = ...)`, `@Tab(shortcut = ...)` | | [Push Notifications](./notifications) | ✅ Implemented | `@Trigger(OnLoad + OnSuccess)`, `Hydratable`, `MicroFrontend` | | [Partial Forms](./partial-forms) | ✅ Implemented | `@FoldedLayout`, `@Section`, nested subform records | | [High-density screens](./high-density) | ✅ Implemented | `@Compact`, `StyleConstants.COMPACT` | | [Audience projection](./audience-projection) | ✅ Implemented | `@Audience` + `@AppContext` field named `audience` | | [Front-office screens](./front-office) | Composition | `TaskQueue` + `EntityHeader` + `Wizard` + `Ledger` + … | | [Entity header](./entity-header) | ✅ Implemented | `EntityHeader` (title, badges, facts, metric) | | [Meter](./meter) | ✅ Implemented | `Meter` (value/max, warn/danger thresholds) | | [Task progress](./task-progress) | ✅ Implemented | `TaskProgress` (done/total pills + CTA) | | [Status list](./status-list) | ✅ Implemented | `StatusList` + `StatusItem` (status chip or action) | | [Task queue](./task-queue) | ✅ Implemented | `TaskQueue` + `QueueGroup`/`QueueItem` | | [Resource grid](./resource-grid) | ✅ Implemented | `ResourceGrid` + `ResourceItem` (availability picker) | | [Offer card](./offer-card) | ✅ Implemented | `OfferCard` (features, price delta, CTA) | | [Add-on picker](./addon-picker) | ✅ Implemented | `AddOnPicker` + `AddOn` (running total) | | [Ledger](./ledger) | ✅ Implemented | `Ledger` + `LedgerLine` (folio breakdown) | | [Payment picker](./payment-picker) | ✅ Implemented | `PaymentPicker` + `PaymentMethod` | | [Process monitor](./process-monitor) | ✅ Implemented | `ProcessMonitor` + `ProcessItem` (health + fix) | | [Notice](./notice) | ✅ Implemented | `Notice` / `@Notice` (inline banner, status, action) | | [Action panel](./action-panel) | ✅ Implemented | `ActionPanel` (categorised "I want to…" overlay, shortcut, show more, hide unpopulated) | | [Matrix grid](./matrix-grid) | ✅ Implemented | `MatrixGrid` (rows × dates, collapsible sections, link cells, in-place editing) | | [Compare and merge records](./record-merge) | ✅ Implemented | `RecordMerge` (records side by side, differences, a pick per field, merge action) | | [App-wide shortcuts and quick launch](./app-shortcuts) | ✅ Implemented | `@AppShortcut(key, route/actionId, code)`, `?` list, codes in the command palette | | [Live header values](./live-header-values) | ✅ Implemented | `HeaderValuesSupplier`, `UICommand.updateHeaderValue`, `LiveHeaderValues.publish` + `@App(liveUpdates)` | | [Idle-session warning](./idle-session) | ✅ Implemented | `@App(idleTimeoutMinutes, idleWarningSeconds, idleSignOutUrl)`, `KeepAliveHandler` | | [Hover details](./hover-details) | ✅ Implemented | `Popover(trigger = hover)`, `@Tooltip("otherField")` on listing cells | | [Drag rows to a destination](./drag-to-a-destination) | ✅ Implemented | `@DragRows("type")` + `DropZone(accept, actionId, parameters)` | | [Kanban](./kanban) | ✅ Implemented | `Kanban` + `KanbanColumn`/`KanbanCard` | | [Timeline](./timeline) | ✅ Implemented | `Timeline` + `TimelineItem` (activity feed) | | [Progress steps](./progress-steps) | ✅ Implemented | `ProgressSteps` (also `@WizardProgress(STEPS)`) | | [Stat / KPI tile](./stat) | ✅ Implemented | `Stat` (value, trend, sparkline) | | [Calendar](./calendar) | ✅ Implemented | `Calendar` month view + `CalendarEvent` | | [Pricing table](./pricing-table) | ✅ Implemented | `PricingTable` + `PricingPlan` | | [Org chart](./org-chart) | ✅ Implemented | `OrgChart` + `OrgNode` | | [Heatmap](./heatmap) | ✅ Implemented | `Heatmap` (calendar heatmap) | | [Funnel](./funnel) | ✅ Implemented | `Funnel` + `FunnelStage` | | [Trend chart](./trend-chart) | ✅ Implemented | `TrendChart` (line/area, dependency-free) | | [Feature grid](./feature-grid) | ✅ Implemented | `FeatureGrid` + `Feature` tiles | | [Testimonials](./testimonials) | ✅ Implemented | `Testimonials` + `Testimonial` | | [FAQ](./faq) | ✅ Implemented | `Faq` + `FaqItem` (collapsible) | | [Callout card](./callout-card) | ✅ Implemented | `CalloutCard` (title, body, CTA) | | [Comment thread](./comment-thread) | ✅ Implemented | `CommentThread` + `Comment` | | [File list](./file-list) | ✅ Implemented | `FileList` + `FileItem` (attachments) | | [Comparison card](./comparison-card) | ✅ Implemented | `ComparisonCard` (side-by-side options) | | [Checklist](./checklist) | ✅ Implemented | `Checklist` + `ChecklistItem` (progress) | ## Anti-patterns Each anti-pattern has a name so it can be recognised quickly — and a pattern that prevents it. | Anti-pattern | Description | Solved by | |---|---|---| | **CRUD Tunnel** | List → detail → back, breaking the flow on every row visit. | [Split View](./split-view) | | **Modal Hell** | Nested modals that destroy orientation. | [Split View](./split-view), [Task-centric page](./task-centric) | | **Spinner Prison** | Freezing the entire screen while something loads. | [Long-running jobs](./long-running-jobs) | | **Filter Amnesia** | Losing filters when navigating away. | Filter state synced to URL — browser bookmarks become saved views | | **Desktop Denial** | Ignoring the keyboard and penalising the expert user. | [Keyboard Shortcuts](./keyboard-shortcuts) — `@Action(shortcut = ...)` | --- # Accessibility URL: https://mateu.io/ux-patterns/accessibility/ > What Mateu guarantees for keyboard and screen-reader users without any code on your part, and how it is verified. **Status:** ✅ Implemented ## Intent In a model-driven framework the developer does not write the HTML. That is usually the problem with accessibility — there is nowhere to fix it — but here it is the lever: **the generator is the only place it has to be right, and fixing it fixes every app at once**, including the ones already written, without a line of user code changing. So none of what follows is opt-in. You get it by using Mateu. ## What you get without doing anything ### Forms Field labels, required state and help text are wired by the design system's own components, so a screen reader announces each control properly. **Validation is announced.** When the server rejects a save, the message is set ON the control (`invalid` + `errorMessage`), which is what makes the design system emit `aria-invalid` and `aria-describedby` inside its shadow root — something no markup outside that boundary could do. The error is also announced through a live region, and **the focus moves to the first rejected field**, so the user is taken to the problem instead of being told there is one somewhere. > Before this, errors rendered as a detached `<ul>` beside the field. Visible, but with no relationship to the input: the control still said `aria-invalid="false"`, nothing pointed at the message, and a screen-reader user pressing Save heard nothing at all. ### Overlays `Dialog` and `Drawer` are real modals: `role="dialog"`, `aria-modal`, and they **own the focus** while open — the focus moves in, Tab and Shift+Tab cycle inside, and closing returns it to the control that opened it. A modeless or layout drawer deliberately does none of this, because it sits alongside the page rather than over it. ### Keyboard Every widget Mateu makes clickable is also operable: task-queue and kanban cards, calendar events, gantt bars, tree nodes, FAQ questions, timeline entries and the rest carry a role, a tab stop, Enter/Space activation and a visible focus ring. Focus rings matter as much as reachability: an element you can Tab to but cannot see is barely better than one you cannot reach. Style them yourself if you want — every such element carries a role you can target: ```css [role="button"]:focus-visible { outline: 2px solid var(--brand-accent); } ``` ### Orientation - **Skip to content** (WCAG 2.4.1) is the first thing Tab reaches, so the navigation is not re-read on every screen. - The content area is a `main` landmark. - **Navigating announces where you landed** — the page title goes into a live region, so a single-page route change is not silent. - After navigating, the focus moves to the new content's heading instead of staying on the menu link you just clicked. Only on real navigations: a re-render never steals the focus out of a field you are editing. ### Announcements Two live regions exist from boot (created up front on purpose — a region filled in the same tick it is created is frequently never announced). Error toasts are **assertive** and interrupt; everything else is polite and waits for a pause. ## Verifying it Two halves, because no single tool sees both: ```bash cd e2e && npx playwright test tests/shared/accessibility.spec.ts cd e2e && npm run a11y # ad-hoc audit over a set of routes ``` - **axe-core** checks the markup rules (labels, contrast, roles, names) on eight representative routes covering every shape Mateu generates. It runs as part of the shared e2e suite, so **every framework adapter gets the same guarantee** and a regression fails the build. - The rest checks **behaviour** — focus trapping, keyboard operability, live regions, focus-on-error — which axe cannot evaluate at all. A `<div @click>` is invisible to axe: it has no way to know the div was meant to be a button. This is exactly where a hand-rolled widget fails, so it is exactly what is pinned. ### One known exclusion `vaadin-tabs` is `role="tablist"` and puts a `<div part="tabs" tabindex="-1">` inside its own shadow root; axe counts that as a child the role does not allow. Nothing in the wire model or in any Mateu renderer can change it — the fix belongs upstream. The carve-out is scoped to that one rule on that one element, so a real tablist mistake still fails the build. ## Native renderers The same guarantees, expressed in each platform's own accessibility API rather than in ARIA. ### React Native (iOS & Android) Mobile screen readers read an accessibility tree that React Native builds only from explicit props — there is nothing to infer it from. Two differences from the web matter: - **A `TextInput` cannot be associated with a nearby label.** There is no `labelFor`, no `aria-labelledby`. So the field's name is handed to the control itself: `"Name, required"`, and `"Name, required, invalid: Cannot be empty"` once the server rejects it. The error goes in the NAME, not the hint — hints are announced last and can be switched off entirely in the OS settings, so a message the user must hear cannot live there. - **A tappable is accessible by default but is not announced AS a button.** Every one now carries a role; icon-only ones ("✕", "➤", "💬") carry an explicit label, since otherwise the glyph is all the user hears. Overlays are marked modal, headings are marked as headings, and a refused save or a completed navigation is spoken through `AccessibilityInfo.announceForAccessibility` — the mobile equivalent of the web renderers' live region. Verify it with the probe (React Native for Web maps the props onto their DOM equivalents, which is what makes this checkable without a device farm): ```bash cd frontend/app/react-native && EXPO_PUBLIC_MATEU_BACKEND_PORT=8080 npx expo start --web --port 19006 cd e2e && RN_SUBMIT=1 node rn-a11y-probe.mjs ``` ### IntelliJ plugin (desktop) Desktop screen readers read Swing's `AccessibleContext`, which Swing populates almost not at all. - **The caption is bound to the control it names** (`setLabelFor`) — the Swing analogue of `<label for>`. Without it the field is announced as an unnamed edit box and the label reads as stray text. - **Composite fields name their inner control too.** A date field is a text box plus a button, a stepper is a spinner wrapping a formatted field; the screen reader follows the FOCUS, which lands inside, so a name on the wrapper alone is never read. - **Required state and `@Help` are spoken**, not just drawn as an asterisk and a grey caption, and a validation error is folded into the control's own description. - Icon-only buttons carry names, and the date picker's trigger is now focusable — browsing months used to be mouse-only. Verify it with the render probe, which prints the accessibility tree beside the visual one: ```bash cd frontend/app/intellij-plugin ./gradlew renderProbe -Pprobe.json=<increment.json> -Pprobe.baseUrl=http://localhost:8080 ``` Each component prints `a11yName`, `a11yDesc` and `labelFor` — a control with no accessible name is indistinguishable from a correct one in a screenshot, which is exactly why the probe reports it. ### Redwood / Visual Builder This renderer shares no core with the web ones, so the guarantees are implemented again in `apps/redwood/poc/a11y.mjs` (bundled into the AMD bridge like the rest of the core). Measured before writing anything: the `oj-sp-*` composition comes out almost clean, for the same reason Vaadin did — those components carry their own accessibility. Two real defects turned up and were fixed: - **The header actions were unreadable.** `AppActionsSupplier` buttons inherited the primary text colour (near-black) on Redwood's dark global header — a contrast ratio of **1.33** where WCAG AA asks for 4.5. These are business labels, not decoration. - **The menu's expand/collapse icons had no name.** `oj-navigation-list` emits them as empty `<a role="button">`; a screen reader announced "button" without saying what for. The app names them from the group they belong to, after the list refreshes. The SPA gaps axe cannot see are covered too: live regions created at boot, a skip link, a `main` landmark, and navigation that announces the destination and moves the focus there — **except on the first load**, where moving it would leave the skip link behind the starting point. ```bash cd frontend/web/monorepo/apps/redwood && npm run serve # :9006, backend demo-vb en :9005 cd e2e && node vb-a11y-probe.mjs ``` One scoped exclusion, same shape as the Vaadin one: `oj-navigation-list` puts its own `role="button"` collapse icon inside the list, which axe counts as a disallowed child of the list's role. Only upstream can change it. ## Writing accessible screens yourself The framework covers the generated UI. Three things are still yours: - **Labels carry meaning.** `@Label("Name")` is what a screen reader reads; `@Help` becomes the description. A field left to its derived name is announced by that name. - **Images say what they show.** Give every `Image` an `alt` — what the picture shows or does, not "image of…". It becomes the `<img>` alt on the web and in Redwood, the accessibility label on React Native and the accessible name in the IntelliJ plugin. An empty `alt` declares the image decorative (screen readers skip it); with no `alt` at all the renderers have nothing to read. ```java Image.builder().src("/logo.png").alt("Acme Corp logo").build() // or new Image("/logo.png", "Acme Corp logo") ``` ```csharp new Image { Src = "/logo.png", Alt = "Acme Corp logo" } ``` ```python fluent.Image(src="/logo.png", alt="Acme Corp logo") ``` ```yaml - type: Image src: /logo.png alt: Acme Corp logo ``` - **Custom fluent components.** If you build a `Component` tree by hand with clickable divs, the framework cannot know they are interactive. Use the same helpers it uses — `onActivate` for Enter/Space, a `role`, and a tab stop. ## Related - [Keyboard shortcuts](/ux-patterns/keyboard-shortcuts/) — action and tab shortcuts - [Slow connections](/ux-patterns/slow-connections/) — busy states also set `aria-busy` --- # Action panel ("I want to…") URL: https://mateu.io/ux-patterns/action-panel/ > A categorised action overlay — the record's actions in columns by category, populated ones first, "Show more", "Hide unpopulated" and a keyboard shortcut. **Status:** ✅ Implemented ![A reservation page with its "I want to…" trigger above the header card](/images/docs/action-panel/reservation-detail.png) ## Intent Back-office records accumulate dozens of actions — modify the routing, add a trace, copy the reservation, open the folio history, go to billing. A toolbar cannot hold them and a flat menu hides how they relate. The pattern used by hospitality and ERP suites (OPERA Cloud's **"I Want To…"**) is a layer over the page with the actions grouped **by category** in columns, the ones with data behind them listed first and emphasised, and a keyboard shortcut to open it. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Return an `ActionPanel` anywhere in the page's components. Each `ActionPanelCategory` is a column; each `ActionPanelItem` dispatches its `actionId` (with its `parameters`) through the standard action mechanism, exactly like a button — so an `@Action` method with that name runs. ```java ActionPanel.builder() .shortcut("ctrl+i") .hideUnpopulatedToggle(true) .categories(List.of( new ActionPanelCategory("Modify", List.of( ActionPanelItem.builder().label("Traces").actionId("traces").count(2).build(), new ActionPanelItem("Routing", "routing"))), new ActionPanelCategory("Go to", List.of( ActionPanelItem.builder().label("Billing").actionId("goTo") .parameters(Map.of("target", "billing")).build())))) .build() ``` **State-dependent actions** need nothing special: the server builds the panel, so it includes (or disables) what applies to the record's current state — `Check in` for an arriving reservation, `Check out` for one in house. ### Options | Parameter | Effect | |---|---| | `label` | the trigger's text — defaults to `I want to…` | | `shortcut` | opens the panel from the keyboard (`ctrl+i`; matched by key or physical key, so it is keyboard-layout independent) | | `maxPerCategory` | actions shown per column before **Show more** (default 10) | | `hideUnpopulatedToggle` | adds a **Hide unpopulated** switch that hides the actions without data, and the columns it leaves empty | | item `populated` | the action has data behind it: listed first and in bold | | item `count` | shown next to the label (`Traces (2)`, `25+` above 25); a count above zero implies `populated` | | item `disabled` | shown but not actionable | Opening, **Show more** and **Hide unpopulated** are client-side state: no server round trip. Picking an action closes the layer. ## Where it works - **Vaadin** — the shared `mateu-action-panel` element (modal layer with focus trap, Esc closes). - **Redwood (Oracle VB)** — JET's `oj-dialog` with `oj-button`s and an `oj-switch` for Hide unpopulated. - **React Native** and the **IntelliJ plugin** — native modal / dialog with the same ordering and cut. - Also available from the C# (`new ActionPanel { Categories = … }`) and Python (`fluent.ActionPanel(categories=…)`) backends. ## Related - [Keyboard shortcuts](/ux-patterns/keyboard-shortcuts/) - [Bulk actions](/ux-patterns/bulk-actions/) — actions over the selected rows of a listing --- # Add-on picker URL: https://mateu.io/ux-patterns/addon-picker/ > Priced extras as toggleable cards with a live running total. **Status:** ✅ Implemented ## Intent Sell small extras — parking, late check-out, an all-inclusive package — as a grid of toggleable cards where the operator (or the customer) sees the running total update live, instead of hunting prices through a form. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `AddOnPicker` component: a `totalLabel` and `currency` for the header-right running total, an optional `actionId`, and a list of `AddOn` cards. Each card has an `icon` chip, a `title`, a muted `description`, and either a price line (`price`, optionally `/ unit`) with a `+`/`✓` toggle, or an `includedLabel` (e.g. a loyalty perk) shown instead of a price and with no toggle. `added(true)` pre-selects a card. ```java @Section("Extras") Component extras = AddOnPicker.builder() .totalLabel("Añadidos").currency("€").actionId("extrasChanged") .items(List.of( AddOn.builder().id("allinc").icon("🍹").title("Paquete All Inclusive") .description("Todo incluido · 7 noches · 2 pax") .price(343.0).unit("estancia").build(), AddOn.builder().id("parking").icon("🅿").title("Parking") .description("Cubierto · Vigilancia 24h") .includedLabel("Incluido Platinum").build(), AddOn.builder().id("late").icon("🕕").title("Late check-out") .description("Hasta las 18:00h") .price(40.0).added(true).build())) .build(); ``` ![Add-on picker](/images/docs/addon-picker/addon-picker.png) Toggling happens client-side (the total recomputes live as the sum of added prices, formatted like the money stereotype). On every toggle, when `actionId` is present, the component dispatches the standard `action-requested` event with parameters `{ "_item": id, "_added": bool, "_total": number }`, so the server can persist each change incrementally. ## When to use it Use an `AddOnPicker` for **multiple optional priced items** attached to a booking/order, where the running total is the feedback that drives the sale. For one big contextual upsell use an [Offer card](/ux-patterns/offer-card/); to compare plans use a [Pricing table](/ux-patterns/pricing-table/); the resulting charges land in a [Ledger](/ux-patterns/ledger/) at check-out. See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/addon-picker-demo`. --- # Advanced create & edit URL: https://mateu.io/ux-patterns/advanced-create-and-edit/ > The Redwood single-page transactional template for a complex object — a sectioned form with a canonical header (save/cancel, timestamp, contextual facts, peer navigation) and either an anchor navigator or a contextual detail slot. The Redwood **Advanced Create & Edit** template is the single-page transactional form for a *complex* object: many fields grouped into sections, a canonical header with the save/cancel affordances and the object's context, and one lateral aid — either a **section index** to jump around a long form, or a **detail slot** with supporting information. It is the heavier sibling of the [simple create & edit](/ux-patterns/create-and-edit/) (`AutoCrud`'s generated `/new`—`/{id}/edit` forms). Mateu doesn't ship a dedicated archetype for it, because by now every region is a piece you already have — it is **composition**, the same slot grammar the archetypes are written in. ## The anatomy, region by region | Redwood region | Mateu piece | |---|---| | Page header — title, **cancel** (left) + **save/primary** (right) | `@Title` + `@Button`/`@Toolbar` (the header places cancel/back left, actions right) | | Header — **last updated** timestamp | [`@Timestamp("Last updated")`](/reference/key-annotations/) on a field | | Header — **contextual facts** ("at a glance") | [`@KPI`](/reference/key-annotations/) label/value fields | | Header — **next / previous object** | [`PeerNavigationSupplier`](/ux/app-structure/#page-anatomy) → prev/next arrows | | **Main** slot — the sectioned form | `@Section` (and `@Zones`/tabs) fields | | **Anchor navigator** — sticky section index | [`@Toc`](/ux-patterns/sections-index/) | | **Detail slot** — a contextual side panel | [`@Aside`](/ux-patterns/layout-inference/#aside--a-content-page-from-a-plain-form) → a `ContentLayout` aside | | Save — validation, optimistic locking, dirty guard | bean-validation annotations, `@Version`, `@ConfirmOnNavigationIfDirty` (automatic on CRUD) | **The rule from Redwood holds:** the anchor navigator and the detail slot are *mutually exclusive* — pick `@Toc` for a long form the user scrolls, or `@Aside` for a form with supporting context beside it, not both. ## Variant A — long form with a section index (`@Toc`) :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @UI("/employee/{id}/edit") public class EmployeeEdit { @KPI @Label("Department") String department = "Engineering"; // contextual facts, header @KPI @Label("Status") String status = "Active"; @Timestamp("Last updated") String updatedAt = "2026-07-26 09:12"; @Section("Identity") @NotEmpty String name; @Section("Identity") String email; @Section("Employment") String title; @Section("Employment") LocalDate hiredOn; @Section("Compensation") @Stereotype(FieldStereotype.money) BigDecimal salary; @Section("Notes") @Stereotype(FieldStereotype.textarea) String notes; @Toolbar @Label("Cancel") URI cancel() { return URI.create("/employees"); } @Button @Label("Save") Message save() { /* persist */ return new Message("Saved"); } } ``` `@Toc` pins a section index to the side and scroll-spies the active section; the header carries the two `@KPI` facts and the timestamp; cancel sits left, Save right. ## Variant B — form with a contextual detail slot (`@Aside`) ```java @UI("/order/{id}/edit") public class OrderEdit { @Timestamp("Last updated") String updatedAt = "2026-07-26 09:12"; @Section("Order") @NotEmpty String reference; @Section("Order") String customer; @Section("Shipping") String address; @Section("Shipping") String carrier; @Aside(width = "22rem") // the detail slot: supporting info beside the form Markdown context = new Markdown( "**SLA** 48h · **Priority** High\n\nLast contact 2 days ago.", null, null); @Toolbar @Label("Cancel") URI cancel() { return URI.create("/orders"); } @Button @Label("Save") Message save() { return new Message("Saved"); } } ``` `@Aside` pulls the `context` panel out of the form body and composes a `ContentLayout` — the form is the `main` region, the panel the `aside`. On narrow viewports the panel stacks under the form. ## When to use CRUD instead If the object is an entity with a repository, `AutoCrud<T>` already gives you the save/cancel flow, validation, optimistic locking (`@Version`) and the unsaved-changes guard for free — annotate the entity's fields with `@Section`/`@Toc`/`@KPI`/`@Timestamp` and you get the advanced form on the generated edit route. Use a plain `@UI` form (as above) when the transaction isn't a single-entity persist. ## Redwood parameter and slot reference What the Redwood `advanced-create-edit` template and its reusable `header-create-edit` expose, and what Mateu gives you for them. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | **Slot** `main` | the form body: `@Section` groups, zones, the fluent `FormField` | ✅ | | **Slot** `detail` (contextual side panel) | `@Aside` on a component-holder field → `ContentLayout` (`position`/`width`/`sticky`) | ✅ | | **Slot** `innerEnd` | — a second docked region is not available on a form; `DataManagement` has docked end/bottom panels (`DockedPanel`) | — | | **Slot** `search` | the app-level smart search bar / ⌘K palette, not a page slot | 🟡 | | Section index | `@Toc` — the sticky section index; a Mateu addition with no Redwood prop | ✅ | | `badge` | `@BadgeInHeader` | ✅ | | `timestamp` | `@Timestamp("Last updated")` | ✅ | | `contextualInfo` key/value facts | `@KPI` fields | ✅ | | `displayOptions {save, saveAndClose, next: on \| off \| unconfigured, bottomActions}` | `AutoCrud` gates and label overrides cover save/cancel; the tri-state grammar exists (`Toggle` + `CrudDisplay`: create, delete, save-and-next in the edit drawer, error banner) but a create-edit PAGE has no `saveAndClose`/`next` | 🟡 | | `displayOptions.contextualInfoSticky` | `@Aside(sticky = …)` for the side panel; the header facts are not stickyable | 🟡 | | `displayOptions.density: standard \| compact` | `@Compact`, set on the view rather than as a template option | 🟡 | | `endOpened: inner \| none` | — the aside is always shown when declared | — | | `pageTitlePlaceholder` (title placeholder in create mode, e.g. "New booking…") | `@TitlePlaceholder("New booking…")`, or `TitlePlaceholderSupplier`; it stands in only while there is no title | ✅ | | `displayOptions {versionHistory, undo, redo}` + `spVersionHistory`/`spUndo`/`spRedo` | ⚪ page-level version history and undo/redo are Fusion Apps concerns, out of scope by decision (the [Undo](/ux-patterns/undo/) pattern covers action-level undo) | ⚪ | | `feedback {customFeedback[], acknowledgmentMessage, pageVersion}` + `openFeedback` | ⚪ the embedded survey is out of scope by decision | ⚪ | Unsaved-changes handling — the dirty guard and, on `AutoCrud`, optimistic locking via `@Version` — is covered by the framework rather than by a template prop. ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Long form + `@Toc` index | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `@Aside` detail slot | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Header (badge, timestamp, facts, title placeholder) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `@Section` edit / add / view-more affordances | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ## Parity Everything here is composition of pieces that render on every renderer and have .NET/Python parity — `[Timestamp]`/`[Section]` and `Timestamp()`/`Section()`, `[Aside]`/`Aside()`, the peer-navigation supplier, and the bean-validation attributes. See [choosing a page template](/ux-patterns/choosing-a-page-template/). --- # Totals & row grouping URL: https://mateu.io/ux-patterns/aggregates/ > Aggregate listing columns over the whole filtered set — totals footer, and group subtotal rows with @GroupBy. **Status:** ✅ Implemented ## Intent Operational listings are also **reports**: the user filtering June's invoices wants the month's total, not just the rows; a sales listing reads better grouped by region with a subtotal per group. Without first-class support, developers export to Excel just to sum a column. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the row class: ```java public class Sale implements Identifiable { String id; @GroupBy String region; // group subtotal rows per region String product; @Aggregate(AggregateFunction.sum) double amount; // totals footer + per-group subtotal @Aggregate(AggregateFunction.count) String invoice; @Override public String id() { return id; } } ``` - **`@Aggregate(sum|avg|min|max|count)`** on a column shows a **totals footer** under the listing with the value computed over the **whole filtered result set** — not just the visible page. `count` counts non-null values. - **`@GroupBy`** on one column groups the rows: it becomes the implicit primary sort (your own sort still applies within each group), and a **group subtotal row** renders whenever the value changes — group value, row count, and each aggregated column's per-group value. - Filtering and searching recompute everything over the filtered set only. ## Pushing the aggregation to the database The default computation runs in memory over `findAll()` — the same cost class as the default `CrudStore.find`. A store backed by a database overrides **one method** and runs a single aggregate query instead: ```java @Override public ListingSummaries summaries(String searchText, Sale filters, List<FilterCriterion> criteria, Map<String, AggregateFunction> aggregates, String groupByField) { // SELECT region, count(*), sum(amount) … GROUP BY region (+ one ungrouped row for totals) return new ListingSummaries(totals, groups); } ``` Declarative `Listing<Row>` classes own their `search(...)`, so they attach the numbers themselves: `ListingData.of(rows).withAggregates(totals).withGroups(groups)` — the `@Aggregate` and `@GroupBy` marks on the row class drive the rendering either way. ## Wire Column metadata carries `aggregate`; the crud metadata carries `groupBy`; each search result carries `aggregates` (totals) and `groups` (`value`, `count`, per-group `aggregates`). Same contract from the Java, .NET and Python servers, rendered by every design system. ## Related - [Filters & Listing](/ux-patterns/filters-and-listing/) — the filters the totals respect - [Saved views](/ux-patterns/saved-views/) — name the slice you keep totalling --- # Application context selector URL: https://mateu.io/ux-patterns/app-context/ > Fix a value (the active hotel, the company, the fiscal year…) for every screen of the app. **Status:** ✅ Implemented ## Intent Fix a value at APPLICATION level — the active hotel in a PMS, the company in a multi-tenant ERP, the business unit, the fiscal year — so every screen of the app works against it without asking again. ## Problem Without an app-level context, every listing and form needs its own "which hotel?" filter, users re-select it on every screen, and nothing guarantees two screens agree on the value. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate a field of the `@UI` app class with `@AppContext`. It renders as a compact selector on the **app header** (next to the theme toggle), visible on every screen: ```java @UI("") @Title("My first Mateu app") public class BackofficeApp { @AppContext(label = "Hotel") HotelSelector hotel; // options from a LookupOptionsSupplier @AppContext Environment environment; // or simply an enum: its constants are the options } ``` The field's type provides the choices: - **An enum** — its constants become the options. - **Any class implementing `LookupOptionsSupplier`** — searched once with an empty text (first page) when the app shell is built: ```java public class HotelSelector implements LookupOptionsSupplier { @Override public ListingData<Option> search(String fieldName, String searchText, Pageable pageable, HttpRequest httpRequest) { return ListingData.of(hotels.stream() .map(h -> new Option(h.id(), h.name())) .toArray(Option[]::new)); } } ``` ![The Hotel context selector on the app header](/images/docs/ux-patterns/app-context.png) ## Reading the context The selected option's value lives in the **app state** under the field's name and travels with EVERY request, so any screen or action reads it from the `HttpRequest`: ```java @Button public Message greet(HttpRequest httpRequest) { var hotel = httpRequest.appContext("hotel"); // "2", or null when nothing is selected ... } ``` **Nothing is selected until the user picks.** A fresh browser has no context: the header picker is empty and `appContext(...)` is `null`, so a screen that needs one shows its unscoped (or empty) state rather than silently working on the FIRST hotel of the list — a preselected option that the user never chose would scope every search, save and export to it. Pick a default yourself when one is right (seed it in the `@UI` class's field initializer, or let the app's `HomeRouteSupplier` redirect to a chooser). This is the contract of every renderer (decided 2026-10-17). An `AutoCrud` typically uses it inside `store()`/`search(...)` to scope the data — the widget stays fully decoupled from the screens. ## Behaviour - **Compact select or searchable picker** — up to 7 options render as a plain select; more options render as a button opening a **searchable panel**: typing filters the loaded options and asks the server for matches beyond the first page (the `_appcontext-search-<field>` action, answered by the field's `LookupOptionsSupplier` or the enum constants). - **Persistent** — the selection (and its label) is stored client-side (one entry per origin) and survives reloads, navigation and new tabs. - **Uniform reactivity** — picking a different value reloads the current route, so whatever screen the user is on rebuilds against the new context. No per-screen wiring. - **Cross-tab sync** — when another tab of the same origin changes the context, every open tab reloads and rebuilds against the new value. - **Explicit app state wins** — the persisted context is merged under any appState entries the components set programmatically. - Several `@AppContext` fields render several selectors (e.g. hotel + fiscal year). ## Header actions Next to the context selectors, the app can contribute **action buttons to the header**: implement `AppActionsSupplier` on the `@UI` app class. Each `actionId` names a public method of the app class (same dispatch as a `@Fab`); an action **with children** renders as a dropdown menu — only the children dispatch. The supplier is evaluated on every shell build, so actions can appear and disappear with server-side state. ```java @UI("") public class BackofficeApp implements AppActionsSupplier { @Override public List<AppHeaderAction> appActions(HttpRequest httpRequest) { return List.of( new AppHeaderAction("sync", "Sincronizar", "vaadin:refresh"), AppHeaderAction.menu("Más", "vaadin:ellipsis-dots-v", List.of( new AppHeaderAction("deploy", "Desplegar"), new AppHeaderAction("purge", "Purgar caché")))); } public Message sync() { ... } // runs when the header button is clicked } ``` Actions returning a `Flux` stream their increments over SSE with the on-screen component as the initiator, so long pipelines (a deploy, a batch job) update their progress dialog as they happen. The .NET and Python backends emit the same `contextActions` wire field: ```csharp public class BackofficeApp : IAppActionsSupplier { public IReadOnlyList<AppHeaderAction> AppActions() => [new AppHeaderAction("sync", "Sync now", "refresh"), AppHeaderAction.Menu("Export", "download", [new AppHeaderAction("exportPdf", "As PDF"), new AppHeaderAction("exportExcel", "As Excel")])]; } ``` ```python class BackofficeApp(AppActionsSupplier): def app_actions(self): return [AppHeaderAction(action_id="sync", label="Sync now", icon="refresh"), AppHeaderAction.menu("Export", "download", [ AppHeaderAction(action_id="exportPdf", label="As PDF"), AppHeaderAction(action_id="exportExcel", label="As Excel")])] ``` ## In YAML A data-authored shell (`type: AppShell`) declares the same pickers and header buttons as data — `contextSelectors:` (static `options` or an `optionsSource` REST source) and `headerActions:` (each navigates with `route`, or runs a shell flow / action-catalogue entry with `actionId`). See [App shell as data › Header extras](/define/yaml/app-shell/#header-extras-pickers-actions-inbox-and-search). Java only: the .NET and Python servers have no `type: AppShell`. ## Other servers The pattern is wire-level, so the .NET and Python backends emit the same selectors: ```csharp [App("Backoffice")] public class BackofficeApp { [AppContext("Hotel")] public IReadOnlyList<OptionDto> Hotel() => hotels.Select(h => new OptionDto(h.Id, h.Name)).ToList(); [AppContext] public FiscalYear Year { get; set; } // enum property } ``` ```python @app("Backoffice") class BackofficeApp: @app_context("Hotel") def hotel(self): return [(h.id, h.name) for h in hotels] # or Option(...) objects, or an Enum return type ``` ## Native renderers The native shells render the same wire field: - **React Native** — selectors at the top of the drawer; session-scoped, picking a value remounts the current screen. Like the web picker, a selector with more than 7 options gains a **search box**: typing filters the loaded options and (debounced) asks the server for matches beyond the loaded page via the same `_appcontext-search-<field>` action — React Native shows it under the drawer selector. ## Principles served - **Workflow over screens** — set once, applies everywhere - **Recoverability** — the context survives reloads; no re-selection tax - **Single source of truth** — screens can't disagree on the active context ## See also - [Audience projection](/ux-patterns/audience-projection/) — an `@AppContext` field named `audience` becomes a persona switch: `@Audience`-marked fields, buttons and menu entries filter to the selected audience (unset → everything visible). --- # App-wide shortcuts and quick launch URL: https://mateu.io/ux-patterns/app-shortcuts/ > Keyboard shortcuts declared once on the app and active on every screen, a "?" list of every shortcut, and quick-launch codes typed in the command palette. **Status:** ✅ Implemented · `@Experimental` ![The "Keyboard shortcuts" list opened with "?"](/images/docs/app-shortcuts/help.png) ## Intent Keyboard-heavy users — a front desk, a call centre, a warehouse — move between a handful of screens all day. They expect **F9 for reservations everywhere**, a way to **see** which keys exist, and the habit of back-office suites: type a short **code** ("RES") and go. A screen's `@Action(shortcut)` only lives on that screen; these belong to the **app**. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Declare them on the app class: ```java @UI("") @App @AppShortcut(key = "f9", route = "/reservations", label = "Reservations", code = "RES") @AppShortcut(key = "f8", route = "/end-of-day", label = "End of day", code = "EOD") @AppShortcut(key = "alt+y", actionId = "syncNow", label = "Sync", code = "SYNC") public class Shell { public Message syncNow() { … } // an action shortcut runs on the app, whatever the screen } ``` | Attribute | Meaning | |---|---| | `key` | the key, in the `@Action(shortcut)` syntax: `f9`, `ctrl+alt+r`, `alt+g` | | `route` | where it goes, relative to the app (made absolute like a menu route) | | `actionId` | or: an app-level action (a public method of the app class) | | `label` | how it is listed; blank = the route's last segment humanized | | `code` | the quick-launch code; blank = none | An entry with neither a key nor a code, or with nowhere to go, is dropped. ### The "?" list **?** (when the focus is not in a text field) opens **Keyboard shortcuts**: the app's shortcuts with their codes, the shortcuts of the screen on show — its `@Action(shortcut)` and `@Tab(shortcut)`, read when the list opens so it is always the current screen's — and the shell's own keys. Picking an app shortcut runs it. ### Quick launch Typing a code in the command palette (**⌘K / Ctrl+K**) lists the shortcut first; **Enter** goes there. With `@App(commandCenter = true)` it is the command center's search; otherwise the shell's ⌘K palette. Codes match case-insensitively; a code or label that starts with what was typed is listed too. ### In YAML and in code A data-authored shell declares the same entries (`AppShortcutEntry` in code, `AppShell.builder().shortcut(…)`): ```yaml type: AppShell shortcuts: - key: f9 route: guests label: Guests code: GST ``` ## Which shortcut wins **The screen's.** A screen's own `@Action(shortcut)` / `@Tab(shortcut)` handles the key first and the app shortcut stands down — so a screen that binds **F9** to its own action keeps it, and F9 means "reservations" everywhere else. On the web the screen listens on `document` and the app on `window`, which the event reaches later, and the app ignores a key the screen has already taken. Two more rules: - A **plain letter** (`g`) never fires while the user is typing in a field; function keys and combinations with Ctrl / Alt / Meta do. - With [access keys](/ux-patterns/keyboard-shortcuts/#access-keys-mode-appaccesskeys--true) on, **Alt + letter** belongs to the access keys; give app shortcuts function keys or Ctrl combinations instead. ## Where it works - **Vaadin** — every screen of the app; the `?` list (`mateu-shortcuts-help`); quick launch in the ⌘K palette and in the command center. - **Redwood (Oracle VB)** — the same keys (`poc/keys.mjs`), the `?` list as an `oj-dialog`, quick launch in the Ask palette. - **IntelliJ plugin** — the keys on every Mateu view (a key the screen uses is left to the screen), a Keyboard shortcuts dialog, a "Go to code…" field. - **React Native** — no keyboard: quick launch is a **Code** field in the drawer, with the codes listed under it. - Also from the C# (`[AppShortcut(Key = "f9", Route = "/reservations", Code = "RES")]`) and Python (`@app_shortcut(key="f9", route="/reservations", code="RES")`) backends. Demo: `demo-admin-panel` → **F9** (merge), **F8** (end of day), **Alt+Y** (sync), **?**, and **MRG** / **EOD** in the command center; `/e2-demo` shows the ⌘K palette (**HOME**). ## Related - [Keyboard shortcuts](/ux-patterns/keyboard-shortcuts/) — a screen's own shortcuts and access keys - [Command center](/ux-patterns/command-center/) --- # Audience projection URL: https://mateu.io/ux-patterns/audience-projection/ > One declared model, projected per audience — staff vs client views of the same screen without duplicating it. **Status:** ✅ Implemented ## Intent The same screen often serves several personas: the front-desk agent needs the internal notes and the folio balance; the guest doing self check-in should see a welcome message and nothing operational. Duplicating the screen per persona forks the model and the two copies drift. Declare **one model** and mark which elements belong to which **audience**; a header switch projects the model per persona. ## Solution Two pieces: :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: 1. **The switch** — an [`@AppContext`](/ux-patterns/app-context/) field named exactly `audience` on the app class. It renders as a selector on the app header and its value travels with every request. An enum gives you the options for free (constants travel as their `name()`): ```java @UI("") public class BackofficeApp { enum Modo { Staff, Cliente } @AppContext(label = "Modo") Modo audience; // ... @Menu entries ... } ``` 2. **The marks** — `@Audience({"..."})` on any form field, `@Button`/`@Toolbar` action method or `@Menu` entry. The values are matched (case-sensitively) against the current `audience` app-context value: ```java @UI("/checkin") public class CheckIn { String bookingCode; // every audience @Audience("Cliente") @PlainText @Multiline String welcome = "¡Bienvenido!"; // only in the guest projection @Audience("Staff") @Multiline String internalNotes; // only in the staff projection @Audience("Staff") @Stereotype(FieldStereotype.money) BigDecimal folioBalance; @Audience("Staff") @Toolbar public Message audit() { ... } // the button disappears for guests } ``` An element may declare several audiences: `@Audience({"Staff", "Manager"})`. ## The unset → everything rule When **no audience is selected** (the selector is empty), **everything is visible**: no projection is active, so the developer — or a supervisor — sees the full model. Selecting an audience activates the projection: elements marked for *another* audience disappear; unmarked elements always stay. | Current audience | Unmarked element | `@Audience("Staff")` element | |---|---|---| | *(unset)* | shown | shown | | `Staff` | shown | shown | | `Cliente` | shown | **hidden** | ## Not access control :::caution[This is a UX projection, not security] `@Audience` decides what is **rendered**, driven by a client-side selector any user can change (or clear — which reveals everything). Sensitive data must be protected with the identity annotations — [`@EyesOnly`](/reference/key-annotations/), `@ReadOnlyUnless`, `@DisabledUnless` — which resolve against the JWT Bearer token. The two compose naturally: `@EyesOnly(roles = "staff") @Audience("Staff")` keeps the element out of the guest *projection* **and** out of reach of non-staff *callers*. ::: ## Where it applies - **Form fields** (including inline subforms and listing columns that go through the standard field filter). - **Action methods** — `@Button` and `@Toolbar` buttons are dropped from the page when their audience doesn't match. - **Menu entries** — `@Menu` fields and methods of the app class. The annotation is composable (semantic annotations can embed it), and the same behaviour ships in the C# (`[Audience("staff")]`) and Python (`Audience("staff")` marker / `@audience(...)` method decorator) backends. ## When to use it Use it whenever one screen serves several personas whose *relevance* differs but whose *rights* don't have to (kiosk vs desk mode, agent vs customer view, novice vs expert density). Pair it with [`@AppContext`](/ux-patterns/app-context/) for the switch and with the security annotations when visibility must actually be enforced. Demo: `/audience-demo` (switch the "Modo" selector between Staff and Cliente). --- # Version diff on the audit trail URL: https://mateu.io/ux-patterns/audit-diff/ > The History dialog groups field-level changes by save moment — each group reads as one version of the record. **Status:** ✅ Implemented ## Intent "Who changed this, when, and **what exactly**?" An audit trail answers it only if the reader can see the changes **as versions** — one save, its author, and every field it touched with old → new values — instead of a flat stream of rows. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Implement `Auditable` on the CRUD entity or view (as before) and return one `AuditEntry` **per field change**, all changes of one save sharing the same `when`: ```java @Override public ListingData<AuditEntry> history(String searchText, AuditFilters filters, Pageable pageable, HttpRequest httpRequest) { return ListingData.from(auditStore.entriesFor(recordId)); // when, who, action, field, old, new } ``` The **History** dialog now renders the trail **grouped by save moment** (`AuditEntry.when` is the listing's `@GroupBy` column): each group subtotal row is one *version* — timestamp and number of fields changed — and its rows are the per-field diff (`field`, `oldValue` → `newValue`, `who`, `action`). Searching and filtering (by author, by field…) recompute the grouping over the filtered trail. ## Restoring a version Restoring is a write decision the framework won't take for you (it can't know whether reverting a price also requires reverting the invoice it produced). The recipe: give the audited entity's crud a [bulk or row action](/ux-patterns/bulk-actions/) that reads the audit rows and writes the old values back through your repository — the [optimistic-locking](/ux-patterns/optimistic-locking/) `@Version` bump keeps the restore itself auditable. ## Related - [Concurrent edit conflicts](/ux-patterns/optimistic-locking/) — versions moving forward - [Totals & row grouping](/ux-patterns/aggregates/) — the grouping machinery this reuses --- # Autosave URL: https://mateu.io/ux-patterns/autosave/ > Eliminate the anxiety of losing work and the doubt of whether it was saved. **Status:** ✅ Implemented — `@AutoSave` ## Intent Eliminate the anxiety of losing work and the doubt of whether changes were persisted. ## Problem A user fills out a long form, the session times out or the tab is accidentally closed, and everything is lost. Or they are left unsure whether the last "Save" actually went through. Both are correctability failures. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the view class with `@AutoSave`. Mateu debounces field changes and automatically triggers the designated save action, keeping the backend in sync without any user gesture. ```java @UI("/orders/{id}/edit") @AutoSave public class EditOrder { private String ref; private LocalDate date; private String notes; public void save() { orderService.update(id, ref, date, notes); } } ``` By default, `@AutoSave` targets the first eligible action on the class. You can specify the action explicitly: ```java @AutoSave(action = "save") ``` ### How it works 1. Any field change triggers a debounce timer (default: ~800 ms). 2. After the debounce window, the `save` action fires automatically. 3. The action is local — it does not trigger navigation or page reload. ### When to use it | Use `@AutoSave` | Use explicit Save button | |---|---| | Long editing sessions where data loss is costly | Workflows with a discrete "commit" concept | | Drafts, notes, configuration | Multi-step wizards | | Any field-by-field editing workflow | Destructive operations | ## Principles served - **Recoverability** — work is never lost to an accidental close or timeout - **Workflow over screens** — saving becomes invisible infrastructure, not a user task - **Minimize navigation** — no "save and stay" vs "save and go" decision required --- # Bulk actions URL: https://mateu.io/ux-patterns/bulk-actions/ > Select rows on a listing and run one action over the whole selection — approve, assign, export. **Status:** ✅ Implemented ## Intent Operate on **many records at once** from a listing — approve 50 invoices, deactivate a batch of products, assign a set of tickets — without visiting each detail view. The listing offers row selection (checkbox column with select-all) and toolbar buttons that act on the selection. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate a method of your `AutoCrud` (or any `Crud`) with `@ListToolbarButton`. It renders as a toolbar button over the listing, and a `List<Row>` parameter receives the **typed selection**: ```java @UI("/invoices") public class InvoicesCrud extends AutoCrud<Invoice> { @Override public CrudStore<Invoice> store() { return store; } @ListToolbarButton @Label("Aprobar seleccionadas") public Message approve(List<Invoice> selection, HttpRequest httpRequest) { selection.forEach(invoice -> service.approve(invoice.id())); return new Message(selection.size() + " facturas aprobadas"); } } ``` - The selection column is enabled by default on every crud listing (opt out by overriding `selectionEnabled()` to `false`). - The frontend keeps the selected rows in the component state (`crud_selected_items`); the framework hydrates them **typed** into any `List<Row>` parameter of the method. - By default the button **requires a selection**: clicking it with nothing selected shows a notice instead of calling the server. Opt out with `@ListToolbarButton(rowsSelectedRequired = false)` for toolbar actions that don't need rows. - `@ListToolbarButton(confirmationRequired = true)` asks for confirmation first — combine both for destructive bulk operations. See [Making it look and read dangerous](#making-it-look-and-read-dangerous) for saying *what* is being confirmed. - The button label follows the usual rules: `@Label` (translated) or the humanized method name. - Return value semantics are the standard action ones: a `Message` toasts, a `PageBanner` shows a banner, `void`/`null` simply re-runs the search so the listing reflects the changes. ## Making it look and read dangerous A bulk action runs over N records at once, so it is the one that most needs to look destructive and to say what the user is about to confirm. Three annotations on the same method, each with one job: | Annotation | Says | |---|---| | `@ListToolbarButton` | **where** the button goes (a crud has two toolbars — this one and the detail view's `@ViewToolbarButton`) | | `@Toolbar` | **how it looks** — `buttonStyle`, `buttonColor`, `buttonSize`, `order` | | `@Action` | **how it behaves** — the confirmation texts, `timeoutMillis`, `sse`, `background`, `idempotent`… | This is the same composition a detail-view method already uses, so nothing is duplicated: ```java @ListToolbarButton(confirmationRequired = true) @Toolbar(buttonStyle = ButtonStyle.secondary, buttonColor = ButtonColor.error, order = 10) @Action(confirmationTitle = "Cancel processes", confirmationMessage = "Cancelling stops every selected process. This cannot be undone.", confirmationText = "Cancel them", confirmationDenialText = "Keep running") @Label("Cancel") public Message cancel(List<ProcessRow> selection) { selection.forEach(process -> service.cancel(process.id())); return new Message(selection.size() + " cancelled"); } ``` Notes: - Each confirmation text falls back **on its own**, so declaring only `confirmationMessage` keeps the framework's title and Yes/No labels instead of blanking them. - The flags are **merged, not overridden**: `@Action.rowsSelectedRequired` defaults to `false` while `@ListToolbarButton` defaults it to `true`, so adding an `@Action` for its texts never disarms the selection guard. - `@Action.id()` is ignored here — the dispatch id belongs to the placement (`action-on-row-<method>`). - Without `@Toolbar` the button keeps the renderer's default look, and without `@Action` it keeps the generic confirmation dialog: existing buttons are untouched. - `@Toolbar(order = N)` fixes the button sequence, which reflection alone does not guarantee. The same three annotations work on a capability `Listing` and on `@ViewToolbarButton` methods of the detail view. ## Built-in bulk delete Every crud listing already ships a bulk **Delete** (selection + confirmation) wired to `CrudStore.deleteAllById(List<IdType>)` — no code needed. ## Other servers Same wire contract from .NET and Python — with the caveat that the appearance and confirmation-text knobs above are **Java only** for now: the ports' `[Toolbar]` / `@toolbar` style a page-toolbar button only (a list-toolbar button keeps the renderer's default look), and neither port carries confirmation texts on the wire (no action of theirs can declare them, bulk or not). ```csharp public class InvoicesCrud : Crud<Invoice> { // … Fetch / Get / Save as in any Crud … [ListToolbarButton] [Label("Approve selected")] public Message Approve(List<Invoice> selection) => new Message($"{selection.Count} approved"); } ``` ```python class InvoicesCrud(Crud[Invoice]): # … fetch / get / save as in any Crud … @list_toolbar_button("Approve selected") def approve(self, selection: list[Invoice]): return Message(f"{len(selection)} approved") ``` ## Principles served - **Workflow over screens** — the operation happens where the user already is: the listing. - **Recoverability** — destructive bulk actions can require confirmation. ## Related - [Filters & Listing](/ux-patterns/filters-and-listing/) — finding the rows to act on - [Task queue](/ux-patterns/task-queue/) — when each item needs individual attention instead --- # Calendar URL: https://mateu.io/ux-patterns/calendar/ > Show events by month, week, day or as an agenda — a schedule, a team calendar, a hotel's property calendar with availability per date. **Status:** ✅ Implemented ## Intent Show dated items — a team schedule, a content plan, bookings — on a familiar month grid, so *when* things happen reads at a glance and clustering is visible. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Calendar` component: `month` is any `LocalDate` in the month to display (the grid is derived from it), and each `CalendarEvent` is placed on its `date` as a small chip. A chip carries an optional accent `color` and an optional `actionId` that makes it clickable (dispatches the standard `action-requested` event). ```java @Section("March 2026") Component calendar = Calendar.builder() .month(LocalDate.of(2026, 3, 1)) .events(List.of( CalendarEvent.builder().title("Sprint planning") .date(LocalDate.of(2026, 3, 2)).color("#3b82f6").build(), CalendarEvent.builder().title("Release 3.1") .date(LocalDate.of(2026, 3, 13)).color("#10b981") .actionId("openRelease").build())) .build(); ``` ![Team calendar](/images/docs/calendar/team-calendar.png) The renderer is dependency-free (a Monday-first CSS grid), themes through the standard CSS variables, marks today, and works in dark mode. ### Views, dates that carry information, dates that act - **`view`** — `CalendarView.month` (default), `week` (Monday to Sunday around the anchor, events with their times), `day` (the anchor date) or `list` (the month's agenda, grouped by date). `month` stays the **anchor** date for every view. - **`views`** — when it lists more than one view, a switcher changes the view **in place** (client-side, no round trip). - **`days`** — a `CalendarDay(date, label, tone)` per date puts a short label in the date's cell and tints it (`info`, `success`, `warning`, `danger`, `neutral`): the maximum availability of a hotel's Property Calendar, a restriction, a closing. - **`dayActionId`** — makes the date cells clickable; the action receives the date as `_date`. - Events gain **`endDate`** (inclusive — a multi-day event appears on each of its days) and **`startTime`/`endTime`** (`"HH:mm"`, shown in the week, day and list views). ```java Calendar.builder() .month(LocalDate.of(2026, 10, 12)) .view(CalendarView.list) .views(List.of(CalendarView.list, CalendarView.month)) .days(List.of(new CalendarDay(LocalDate.of(2026, 10, 30), "Avail 3", "danger"))) .dayActionId("openDay") .events(List.of(CalendarEvent.builder().title("Tech Summit").date(LocalDate.of(2026, 10, 15)) .endDate(LocalDate.of(2026, 10, 18)).startTime("09:00").endTime("18:00").build())) .build(); ``` ## Calendar page (the RDS template) The `CalendarPage` archetype turns the component into the full Redwood **Calendar** page template: a calendar toolbar — previous/next chevrons, a *Today* button, the view switcher and an optional primary *+ Create* button — over the calendar. Navigation re-runs `events(month)` for every month the displayed period touches (so events can be fetched per month), and clicking an event runs `actionOn(event)`. Override `views()` to offer the week, day and list views (the chevrons then step by the view's period), `days(from, to)` to put a label and a tone in each date, and `daysClickable()` + `actionOnDay(date)` to make the dates act — the shape of OPERA's Property Calendar (demo: `demo-vb-pms` `/home/calendar`). ```java @UI("/calendar-demo") @Title("Housekeeping calendar") public class HousekeepingCalendar extends CalendarPage { @Autowired HousekeepingSchedule schedule; // your use case / repository @Override protected List<CalendarEvent> events(LocalDate month, HttpRequest httpRequest) { return schedule.eventsOf(month); // fetched per month } @Override protected Object actionOn(CalendarEvent event, HttpRequest httpRequest) { return URI.create("/bookings/" + event.id()); } @Override protected boolean showCreate() { return true; } @Override protected Object createAction(HttpRequest httpRequest) { return URI.create("/todo-list-demo"); } } ``` ![Calendar page](/images/docs/calendar/calendar-demo.png) - `initialMonth()` defaults to the current month; the displayed month is page state, so ‹ / › and *Today* round-trip through the backend and re-fetch. - Works on every renderer — Vaadin, Redwood (JET has no calendar component, so the grid is drawn with Redwood's tokens; the switcher is `oj-buttonset-one`), React Native and the IntelliJ plugin — and on the .NET (`CalendarPage`) and Python (`CalendarPage`) backends. ## Redwood parameter and slot reference What the Redwood `calendar` template exposes, and what Mateu gives you for it. This is the template with the **largest open surface** of the set — the underlying component is a month grid. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `calendarEvents` | `events(LocalDate month, HttpRequest)` — fetched per displayed month, server-side | ✅ | | Month navigation | ‹ / › / *Today* round-trip through the backend; `initialMonth()` sets the start | ✅ | | `displayOptions.createEvent` / `createEventLabel` | `showCreate()` + `createAction(HttpRequest)` | ✅ | | Event click | `actionOn(CalendarEvent, HttpRequest)` — return a `URI` to navigate | ✅ | | `selectedViewValue` + `displayOptions {monthView, weekView, dayView, listView}` | `views()` (+ `Calendar.view`/`views`): month, week, day and list | ✅ | | Date cell content / date click | `days(from, to)` labels and tones; `daysClickable()` + `actionOnDay(date)` | ✅ | | `displayOptions.firstDayOfWeek` | — the grid is Monday-first | — | | `displayOptions {eventCounter, eventSortCriteria, eventDetailMode}` | — | — | | `calendarProviders[]` + `visibleCalendars[]` (multi-calendar) | — one event source per page | — | | `selectionMode: none \| single \| multiple` | events are actionable, not selectable | 🟡 | | `readonly` | the calendar is read-only by design; pair it with a form to create or move events | ⚪ | | `emptyState {primaryText}` | — | — | | `eventDetailActions[]` | a single `actionOn` per event | 🟡 | | **Slots** `eventTemplate` / `tooltipTemplate` / `eventDetailTemplate` | — events render as chips with an optional accent `color`; the chip shape is not overridable | — | | `spCalendarEventCreate` / `Update` / `DetailAction` | `createCalendarEvent` / `openCalendarEvent` cover create and open; there is no update event | 🟡 | ## When to use it Use a `Calendar` to show **dated events by month, week, day or as an agenda** for scanning and light interaction (click an event to drill in). It is read-only by design; for scheduling/drag-to-create, pair it with a form that creates or moves events and re-renders. Demo: `/calendar-demo`. --- # Callout card URL: https://mateu.io/ux-patterns/callout-card/ > A themed call-to-action block — an upgrade prompt, a tip, a warning banner. **Status:** ✅ Implemented ## Intent Draw attention to a single message with an action — an upgrade prompt, a "you're all set" confirmation, a trial-ending warning, a payment-failed alert — as a themed, accented block with an optional call-to-action button. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `CalloutCard` component: an icon, a title, a description and an optional CTA (`ctaLabel` + `actionId`). `theme` — `info`, `success`, `warning` or `danger` — tints the background and accent and colors the CTA; the button dispatches the standard `action-requested` event. ```java CalloutCard.builder() .theme("warning").icon("⚠️") .title("Trial ends in 3 days") .description("Upgrade now to keep your projects and data.") .ctaLabel("Upgrade").actionId("upgrade") .build(); ``` ![Callouts](/images/docs/callout-card/callouts.png) The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. Unlike `@Banner` (page-level notices below the header), a `CalloutCard` is a first-class component you place anywhere in the layout. ## When to use it Use a `CalloutCard` for **an inline, actionable highlight**. For page-level notices use `@Banner`; for a friendly empty screen use `EmptyState`. Demo: `/callout-demo`. --- # Checklist URL: https://mateu.io/ux-patterns/checklist/ > A task checklist with a progress bar — onboarding, a setup guide, acceptance criteria. **Status:** ✅ Implemented ## Intent Show a set of tasks with their completion state and overall progress — an onboarding flow, a setup guide, a release checklist, acceptance criteria — so what's left to do reads at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Checklist` component: an optional `title` and a list of `ChecklistItem`s (label, `done` flag, optional `actionId`). The header shows `done / total` and a progress bar; toggling a checkbox flips it locally and, when the item has an `actionId`, dispatches the standard `action-requested` event (with the item and its new state) so a developer method can persist it. ```java @Section("Onboarding") Component checklist = Checklist.builder() .title("Set up your workspace") .items(List.of( ChecklistItem.builder().label("Create your account").done(true).build(), ChecklistItem.builder().label("Verify your email").done(true).build(), ChecklistItem.builder().label("Invite your team").actionId("toggle").build(), ChecklistItem.builder().label("Publish your first screen").actionId("toggle").build())) .build(); ``` ![Onboarding checklist](/images/docs/checklist/onboarding.png) The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. Toggling updates the progress bar immediately; the server round-trip (via `actionId`) is optional for persistence. ## When to use it Use a `Checklist` for **tasks with completion state**. For a linear multi-step process indicator use `ProgressSteps`; for a kanban of work items use `Kanban`. Demo: `/checklist-demo`. --- # Choosing a page template URL: https://mateu.io/ux-patterns/choosing-a-page-template/ > A decision guide — from your user's goal to the right Mateu archetype — modeled on the Oracle Redwood page-template taxonomy. Mateu gives you a **library of full-page templates** (archetypes). This page is the decision guide that picks the right one, the way an enterprise design system teaches you to: start from the *user's goal*, narrow by *data density*, land on a *template*. The taxonomy follows the Oracle Redwood page templates — the clearest public reference for this — expressed once in Mateu and rendered by every design system. **This choice is the normal starting point of building a UI**, not an afterthought: list the screens your app needs, then run each one through this guide. Picking the template per screen is a decision you make — Mateu infers the template itself only in two specific cases (see [the last section](#what-mateu-can-infer--and-what-it-cant)); everything below the template (layout, widgets, sections) is where inference does the heavy lifting. For the catalog (template → Mateu piece → demo route) see [Page templates](/ux-patterns/page-templates/). This page is the *how do I pick one*. For each of the six page types with its anatomy and a minimal YAML and code example, see [Page types](/ux/page-types/). ## Step 1 — Category, from the user's goal Every page answers one of three goals. Ask what the user is fundamentally doing: | Category | The user is… | Read | Create / Edit | |---|---|---|---| | **Overview** | getting a high-level, summarized picture to plan next steps | ✅ | ❌ | | **Detail** | exploring one entity in depth, moving laterally across peers | ✅ | ❌ | | **Transactional** | creating or updating one or more business objects | ❌ | ✅ | If the user only **reads aggregated** information → Overview. If they **read one thing** in depth → Detail. If they **change** things → Transactional. ## Step 2 — Data density, from the content Every template is sized with one of three widths — Mateu's `@PageWidth` / `PageWidthSupplier` ([page width](/ux-patterns/page-templates/)): | Width | Use for | Mateu | |---|---|---| | **Fixed** | text-heavy pages that don't benefit from extra width (too-wide text is harder to read) | `@PageWidth(FIXED)` | | **Full width** | high-density data — grids, tables, Gantt charts — that should fill the viewport | `@PageWidth(FULL_WIDTH)` | | **Edge to edge** | canvases with multiple panels or drawers, no margins | `@PageWidth(EDGE_TO_EDGE)` | When you don't set it, Mateu infers it from the content (full-bleed canvases → edge-to-edge, dense datagrids → full width, everything else → fixed). Set it explicitly only when the inference is wrong for your case. ## Step 3 — Template, from the shape of your data ### Collection pages (many records) | You need… | Template | Mateu | |---|---|---| | Full CRUD of one entity (list + create/edit/view/delete) | **Create & Edit (simple)** | [`AutoCrud<T>`](/ux-patterns/create-and-edit/) | | A listing that grows à la carte — search, filters, detail, edit, create, delete as needed | **Smart Filter and Search** | [`Listing<Row>` + capability interfaces](/java-user-manual/build/capability-listings/) | | A standalone search-first page (typed facets, starts empty) | **Smart Search page** | [`SmartSearchPage<Filters, Row>`](/ux-patterns/smart-search/) | | A hero banner over a faceted search (landing + collection) | — | [`HeroSearch<Filters, Row>`](/ux-patterns/hero-search/) | | Pending work as counted buckets of actionable cards | **To-do list** | [`TodoList<Row>`](/ux-patterns/to-do-list/) | | A month grid with event actions | **Calendar** | [`CalendarPage`](/ux-patterns/calendar/) | | A searchable list with an in-place detail pane | **Collection Detail** | [`CollectionDetail<Row>`](/ux-patterns/collection-detail/) | ### Overview pages | You need… | Template | Mateu | |---|---|---| | A prioritized snapshot: KPIs + charts to start the day | **Dashboard Landing** | [`Dashboard`](/ux-patterns/dashboard/) | | A visually engaging entry point into a workflow, with CTAs | **Welcome** | [`Welcome`](/ux-patterns/welcome-page/) + `@WelcomeBanner` | ### Detail pages (one entity) | You need… | Template | Mateu | |---|---|---| | An overview across the top + several categories in lateral panels | **Foldout** | [`Foldout`](/ux-patterns/foldout/) | | The simplest detail page: context strip over property cards, with a record switcher | **General Overview** | [`GeneralOverview<Row>`](/ux-patterns/general-overview/) | | A sticky key-info panel + tabbed detail for one item | **Item Overview** | [`ItemOverview`](/ux-patterns/item-overview/) | | Extra read-only info about an object *without leaving the page* (side panel) | **General Drawer** | [`Drawer`](/ux-patterns/drawer/#general-drawer--read-only-detail-subtitle-sizes-maximize-peer-navigation) (subtitle/size/maximizable/peer-nav) | | The same, docked at the bottom (expand/collapse) | **Bottom Drawer** | [`Drawer`](/ux-patterns/drawer/#bottom-drawer-drawerpositionbottom--collapsible) (`DrawerPosition.bottom` + `collapsible`) | ### Transactional pages (create / edit) | You need… | Template | Mateu | |---|---|---| | Create/edit a record — validation, optimistic locking, dirty guard | **Create & Edit (simple)** | [`AutoCrud<T>`](/ux-patterns/create-and-edit/) | | The same for a complex object: section index + a contextual detail panel | **Advanced Create & Edit** | [`@Toc`](/ux-patterns/sections-index/) (anchor nav) *or* [`@Aside`](/ux-patterns/layout-inference/#aside--a-content-page-from-a-plain-form) (detail slot) + `@KPI`/`@Timestamp`/peer-nav — see [Advanced create & edit](/ux-patterns/advanced-create-and-edit/) | | Create/edit in a panel that slides over the listing (which never unmounts) | **Create & Edit Drawer** | [`editInDrawer()`](/ux-patterns/drawer/#crud-editing-in-a-drawer-editindrawer) | | A list with an in-place detail pane and actions on the selected item | **Collection Detail** | [`CollectionDetail<Row>`](/ux-patterns/collection-detail/) | | A multi-step process, 2–25 steps, with a lateral progress rail | **Guided Process** | [`Wizard`](/ux-patterns/wizard/) + `@WizardProgress(RAIL)` | | A short sub-flow or batch action inside a drawer (≤5 steps) | **Guided Process Drawer** | [`Drawer`](/ux-patterns/drawer/) + `EmbeddedView(wizard)` (drawn as a generic wizard in the drawer) | | A dense datagrid you edit in place, optionally switching to a Gantt | **Data Management** | [`DataManagement`](/ux-patterns/data-management/) (grid ⇄ Gantt switch) | | A scheduling canvas: Gantt + docked detail panel | **Gantt page** | [`GanttPage`](/ux-patterns/gantt/#gantt-page-template-ganttpage-archetype) | Every template in the tables above is available today — each links to its archetype, annotation or composition. ## How the choice is encoded - **Category** → the `pageType` on the wire (`landing`/`collection`/`detail`/`form`/`process`/ `dashboard`). Archetypes declare theirs; set it explicitly with `@PageTemplate(PageType.X)`, or with `pageType:` on a YAML page definition. - **Density** → `@PageWidth(FIXED | FULL_WIDTH | EDGE_TO_EDGE)`, or leave it inferred. - **Template** → extend the archetype (or set the flag) from Step 3. Everything below is composition of wire components that already render on every renderer — except where the Redwood column of [Page templates](/ux-patterns/page-templates/) says otherwise. You are never forced onto a template: a plain `@UI` class with declared fields still infers a valid layout ([layout inference](/ux-patterns/layout-inference/)). The templates are opinionated rails on top, not a requirement. ## What Mateu can infer — and what it can't Be clear about the division of labor. **Choosing the template is your decision** — that's this guide, and it's the normal path, not a failure of the framework. What Mateu infers: - **Below the template, a lot.** Field types → widgets, field count/weight → columns and sections, read-only shape → tabs, and so on ([layout inference](/ux-patterns/layout-inference/)). This is why an archetype with a nearly-empty body already renders well. - **The template itself, in exactly two cases.** A class whose shape is fully derivable composes its template with no archetype: consecutive `MetricCard` fields → a **Dashboard**; only `Button` fields + `@Panel` tiles → a **Welcome** landing (`@AutoPage(false)` opts out). - **A hint, for a few more.** When a plain form structurally resembles an archetype (a selectable list next to a detail pane → CollectionDetail), the advisor logs a one-time suggestion — but it doesn't compose it; you decide. - **Convenience shortcuts are still explicit choices.** `@Aside` (one field → contextual side panel of a content-page) or `@Toc` (section index) are annotations you add — tiny decisions, but yours. Everything above is the same uniform slot grammar the archetypes themselves compose. ## Status The full Redwood page-template catalog is covered — the Overview, Detail and Transactional families, the drawers (General, Bottom, Create&Edit, Guided Process), the dense canvases (Data Management, Gantt page) and the composed **Advanced Create & Edit** — plus the extras Redwood doesn't name. All of it is the same uniform slot grammar (a canonical page header + `ContentLayout` main/aside/footer), so every template renders on Vaadin and the native renderers and has .NET/Python parity; on Redwood, check the template's row in [Page templates](/ux-patterns/page-templates/). What's left is polish, not coverage: deeper variants (a bottom + side drawer used *simultaneously* on the Gantt page, batch flows in the Guided Process Drawer) and closing the Figma design-to-code loop for the newest kinds. --- # Client errors in the server log URL: https://mateu.io/ux-patterns/client-error-log/ > The errors a renderer shows or hits are posted to the backend and written as one structured log line each, so they can be found later. **Status:** ✅ Implemented (Vaadin and Redwood renderers; every Java backend: Spring MVC, WebFlux, Micronaut, Quarkus, Helidon MP) ## Intent The user saw «Your session is no longer valid» — and nothing on the server says so. When the request never reached the app (a gateway rejected it, the network dropped it) or the failure was the browser's own (an uncaught exception), the error only ever existed on one screen. You cannot debug what you cannot find. ## Solution Both renderers report the errors they hit or show to `POST <baseUrl>/mateu/v3/client-log`, on the same origin and with the same `Authorization: Bearer …` header as every other `/mateu/v3` call — so a gateway routes and authenticates it like the rest. The backend writes **one line per report** on the logger `mateu.client`, at `WARN`: ```text WARN mateu.client : client-error {"level":"error","kind":"unauthorized","renderer":"redwood","message":"Tu sesión ya no es válida. Vuelve a iniciar sesión.","detail":"Mateu → HTTP 401","url":"/mateu/v3/sync/bookings","route":"/bookings","actionId":"save","pageUrl":"https://app.example.com/bookings","firstAt":"2026-10-05T14:02:11.120Z","lastAt":"2026-10-05T14:02:11.120Z","userAgent":"Mozilla/5.0 …","status":401,"count":1,"user":"ana"} ``` Nothing to configure: it is on by default. Turn it off with `mateu.client-log.enabled=false` (the endpoint then answers 404 and the renderers stop reporting for that page). The logger is a normal SLF4J logger, so `logging.level.mateu.client=OFF` silences the lines without touching the endpoint. The endpoint takes anonymous reports (an expired session is one of the things it reports), so it is **rate-limited**: at most 60 reports a minute per authenticated user, else per client address (`mateu.client-log.max-reports-per-minute`); the rest are dropped and answered `429`, which the renderers take as "try later", not "stop". Behind a reverse proxy every client shares the proxy's address — lower the cap, or let the proxy limit it. ### What is reported | Source | `kind` | |---|---| | A request failure the user is shown (the error toast / band) | `offline`, `timeout`, `server`, `unauthorized`, `forbidden`, `notFound`, `client`, `unknown` | | An uncaught error (`window` `error`) | `js-error` | | An unhandled promise rejection | `unhandled-rejection` | | The request-loop circuit breaker tripping (Vaadin) | `request-loop` | Never reported: `cancelled` (an abort is our own decision), failures of the report call itself (no loops), `ResizeObserver loop` noise. ### Fields `level`, `kind`, `renderer` (`vaadin` / `redwood`), `message` (what the user saw, ≤ 1000 chars), `detail` (the underlying error text), `status`, `url` (the failed request), `route`, `actionId`, `pageUrl`, `source` (file:line:col of a JS error), `traceparent` (when the request carried one), `firstAt` / `lastAt` / `count`, `dropped`, `userAgent`, `stack` (≤ 4000 chars), and `user` — the authenticated principal's name, added by the server. URLs lose their `#fragment`, and query values such as `code`, `state` and `access_token` are masked as `***`. ### Volume control - **De-duplication.** The same error (kind, status, message, url, action, first stack line) within a minute is one line: the first occurrence is sent after ~2 s; repeats are summed into one more line (`count`, `firstAt`, `lastAt`) when the minute closes or the page is hidden. - **Rate limit.** At most 20 lines a minute per page; lines over the limit are counted in the next line's `dropped`. - **Batching.** Lines go out as a JSON array, kept under the server's 16 KB body limit (413 above it). - **Transport.** `fetch` with `keepalive` and the Bearer token. `sendBeacon` cannot carry headers, so it is only the last resort on `pagehide` when there is no token. ## Finding them in Loki Each pod's stdout carries the lines, so with Alloy/Promtail shipping container logs: ```logql {namespace="<ns>"} |= "client-error" ``` Narrow it down by parsing the JSON after the prefix: ```logql {namespace="<ns>"} |= "client-error" | regexp `client-error (?P<report>\{.*\})` | line_format "{{.report}}" | json | kind="unauthorized" ``` ## Backends Every Java adapter serves it on any path ending in `/mateu/v3/client-log`, with the same framework-neutral handling (`io.mateu.core.infra.ClientErrorLog`): a servlet filter on Spring MVC and a `WebFilter` on WebFlux (both ordered after Spring Security's chain, so it is secured like the other Mateu calls), a dedicated route of the generated controller on Micronaut, and a route on the Vert.x router (Quarkus) or the Helidon routing (Helidon MP). Turn it off with `mateu.client-log.enabled=false`; the endpoint then answers 404, which the renderers read as "no endpoint here" and stop reporting for the page. ## Related - [Session expiry](/ux-patterns/session-expiry/) — the 401 handling whose failures this makes visible - [Slow connections](/ux-patterns/slow-connections/) — how failures are classified --- # Client-side caching URL: https://mateu.io/ux-patterns/client-side-caching/ > How Mateu makes return visits feel instant — it caches what a screen looks like (and, for screens you mark static, its data too) so navigation doesn't wait on the backend, while a served UI keeps the server as its source of truth. **Status:** ✅ Implemented ## Intent Make returning to a screen feel instant. Mateu caches what a screen *looks like* in the browser and reuses it on the next visit, so navigation no longer waits on a backend round-trip — while the server stays the source of truth for the UI. It is built into the framework: you get most of it on every renderer with no code, and you can opt a screen into the strongest form with a single annotation. ## Problem Every Mateu screen normally asks the server what to render. That is what lets the server infer and drive the UI — but for a *declared* screen (a class and its annotations) the structure barely changes between requests, so re-fetching all of it on every visit is a round-trip you can usually avoid. On a slow connection that round-trip is exactly what makes a back-and-forth navigation feel sluggish. ## How it works Three layers, from fully automatic to opt-in. They compose: the first paints the layout instantly, the second shrinks the follow-up, and the third removes it. ### 1. Instant structure (automatic) The first time you open a screen, Mateu remembers its **structure** (the layout: sections, fields, tabs, columns — never the data) in the browser. On a return visit it paints that real structure immediately instead of a blank page or a generic loading skeleton, *and* still sends the normal request in the background. When the server responds, its answer replaces the prediction. This is **stale-while-revalidate**: the cache is a prediction, the server is the authority. Because only the structure is cached — never the data — you never see stale business data, and a structure that has drifted (a new deployment, a screen that looks different for a different user) corrects itself within that one navigation. ### 2. Smaller responses (automatic) On that background request the client tells the server which structure it already holds (an ETag). If nothing changed, the server replies with **only the data** and omits the layout — a much smaller response. So a return visit paints instantly *and* revalidates cheaply. Entirely transparent; there is nothing to configure. ### 3. Skip the round-trip — `@StaticView` (opt-in) :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Some screens never change at all: a help or "about" page, a fixed reference screen, a dashboard of constants. Mark the view `@StaticView` and Mateu caches its **whole response** (structure *and* data) for the session. On a return visit within that session it renders from the cache and makes **no server call** at all. ```java @Title("About") @StaticView @PlainText public class About { String product = "Mateu"; String tagline = "Model-driven UI for Java."; String version = "3.0"; } ``` ```yaml # src/main/resources/specs/ui/routes.yaml type: Routes routes: - route: about viewModel: com.example.About ``` `@StaticView` is a promise you make, much like `@Action(idempotent = true)`: you are telling Mateu the screen's content does not vary. Use it only when that is genuinely true. **Do not** use it on a screen whose content depends on: - data (anything loaded from a store), - the logged-in user or their permissions, - the current time, - `${…}` interpolation of live state. If you mark such a screen static, the client will keep showing the first rendering for the rest of the session. When in doubt, leave it off — layers 1 and 2 already make the return visit cheap. The skip is **scoped to the browser session** on purpose: a full page reload always reloads the screen, so a new deployment is picked up automatically the next time the tab is refreshed — no cache-busting to manage. ## What you get for free Layers 1 and 2 need **no code and no annotation**. Every declared screen already: - paints its real structure instantly on a return visit, and - revalidates with a small, data-only response when its structure hasn't changed. It all lives in the shared frontend (`libs/mateu`), so it applies to every renderer built on it — Vaadin. **The Redwood/Visual Builder line does not use that frontend** (its transport is its own core) and has **no screen cache**: every navigation there waits on the backend. ## Other languages `@StaticView` has the same effect in the C# and Python backends: ```csharp [UI("/about")] [Title("About")] [StaticView] public class About { public string Product { get; set; } = "Mateu"; } ``` ```python @ui("/about") @title("About") @static_view class About: product: str = "Mateu" ``` ## Turning it off / measuring The caching is safe to leave on, but if you want to compare with and without it (for example, to measure the difference on a slow link), you can disable each layer from the browser console: - Structure cache (layers 1–2): `localStorage['mateu-route-structure-cache-off'] = '1'`, then reload. - Static-view skip (layer 3): it is in-memory and session-scoped, so a plain reload already re-fetches; there is nothing persistent to clear. ## Related - [Slow connections](/ux-patterns/slow-connections/) — the transport's busy feedback, retries and offline handling that this builds on. - [`@StaticView` in Key annotations](/reference/key-annotations/#staticview). --- # Collection detail URL: https://mateu.io/ux-patterns/collection-detail/ > A searchable list on the left, the selected item's detail on the right — the Redwood "Collection Detail" template as a Mateu archetype. :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The `CollectionDetail<Row>` archetype renders a **searchable list of items on the left** (clickable cards with title, caption and badges) and the **selected item's detail on the right**, re-rendered in place on every selection — no navigation, no page reload. ```java @UI("/hotel-directory") @Title("Hotel directory") public class HotelDirectory extends CollectionDetail<Hotel> { @Override protected List<Hotel> rows(String searchText, HttpRequest rq) { ... } @Override protected String idOf(Hotel h) { return h.id(); } @Override protected String titleOf(Hotel h) { return h.name(); } @Override protected Component detail(Hotel h, HttpRequest rq) { return Card.builder().title(new Text(h.name())).build(); // any component } } ``` Optional hooks: `captionOf`/`badgesOf` enrich the list cards, `listLabel(count)` labels the list (default `"1 item"` / `"N items"`, the built-in texts `item` and `items` through your `Translator`), `emptyDetail()` customizes the right pane before any selection, `listWidth()` sizes the list column (default `24rem`). The search box filters as the user types (debounced 400 ms — the archetype declares the auto-save trigger itself, no annotation needed). The detail pane can be any component tree; when the detail needs its own actions or lifecycle, return an embedded routed island (the `DetailIsland` pattern) instead of a plain card. ## Redwood parameter and slot reference What the Redwood `collection-detail-page` template (and its `collection-detail-stacker`) exposes, and what Mateu gives you for it. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | **Slot** default (the list) | `rows(searchText, HttpRequest)` + `idOf`/`titleOf`, enriched by `captionOf`/`badgesOf` | ✅ | | **Slot** `detailTemplate` (receives the item's `data`) | `detail(Row, HttpRequest)` — server-side, so it receives the row itself rather than a client-side template binding | ✅ | | **Slot** `noSelection` | `emptyDetail()` | ✅ | | **Slot** `search` | the list's own search box (debounced 400 ms, declared by the archetype) | ✅ | | **Slot** `announcement` (aria-live) | live regions are installed client-side for a11y, but the backend cannot declare announcement content | 🟡 | | `selectedItems` (**plural** — multi-selection) | selection is single: `selectCollectionItem` sets one row | — | | `selectContext` switcher | — the record switcher is only available inside `GeneralOverview` | — | | List column sizing | `listWidth()` (default `24rem`), `listLabel(count)` — Mateu additions | ✅ | | `displayOptions.mobileMenu` | the renderer stacks list and detail on narrow viewports; not configurable | 🟡 | | `displayOptions.density: standard \| compact` | `@Compact`, set on the view rather than as a template option | 🟡 | | `displayOptions.goToParent` + `spGoToParent` | breadcrumbs approximate it | 🟡 | | `displayOptions.inFlowBack` + `spInFlowBack` | — | — | | `spSecondaryAction` | — page-level secondary actions come from the toolbar, not from the template | 🟡 | ## Demo `demo-admin-panel/.../collectiondetail/HotelDirectory.java` (`/collection-detail-demo`). Tests: `CollectionDetailSyncTest`. --- # Column chooser URL: https://mateu.io/ux-patterns/column-chooser/ > Each user shows, hides and reorders listing columns — persisted per listing, no code needed. **Status:** ✅ Implemented ## Intent The developer picks sensible default columns; the accountant wants the tax column, the operator wants it gone and the phone first. **Column personalization is per user, per listing** — a staple of SAP/Salesforce-class tables that shouldn't require code. ## Solution Every crud/listing header has a **columns button** next to the smart search bar. Its panel lists the columns with: - a **checkbox** to show/hide, - **↑/↓** to reorder, - **Reset** to return to the developer's defaults. Preferences persist client-side (localStorage `mateu-column-prefs`), **per listing route** and per browser profile — the same scoping as [saved views](/ux-patterns/saved-views/). No annotations, no server code; works on every design system. Safety rails: identifier and action columns (the view/select/menu columns the listing needs to function) are never offered for hiding and keep their absolute positions while reordering; totals footers and group subtotal rows follow the visible columns automatically. ## Related - [Saved views](/ux-patterns/saved-views/) — the same per-route personalization for conditions - [Totals & row grouping](/ux-patterns/aggregates/) — footers that follow the chosen columns --- # Command Center (Ask Oracle) URL: https://mateu.io/ux-patterns/command-center/ > An always-present FAB that opens a full-screen palette to reach any screen, search all your data and open recent work from anywhere — and, optionally, replace the app bar entirely. **Status:** ✅ Implemented ## Intent Traditional menus run out of room: as an app grows, the navigation bar can only surface a fraction of what the user can actually do. The **command center** — Mateu's take on Oracle Redwood's *Ask Oracle* pattern — solves this with a single **floating action button (FAB)** that is always present in the bottom-right corner. Pressing it (or `⌘K` / `Ctrl+K`) opens a **full-screen palette** that unifies, from anywhere in the app: - **Go to any screen** — the whole menu, flattened and searchable (including nested submenus). - **Search all your data** — entity results across the app, when the app class implements [`GlobalSearchSupplier`](/ux-patterns/global-search/). - **Recent screens** — the last places the user visited (kept client-side). - **Ask the AI assistant** — when the app has an AI assistant configured, a one-tap hand-off. Because everything reachable lives behind one discoverable, touch-friendly control, you can optionally **drop the app bar entirely** for a cleaner, more focused UI. ## Enabling it :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Opt in on the `@App` class. Nothing else changes — the FAB is simply added on top of your existing shell: ```java @UI("") @App(commandCenter = true) public class MyApp implements GlobalSearchSupplier { // GlobalSearchSupplier is optional @Menu MyDashboard dashboard; @Menu Customers customers; // ... } ``` - The **FAB** appears bottom-right. If the app also has FABs (`@Fab`) or the AI assistant, they stack above it. - **Global data search** lights up automatically when the app class implements `GlobalSearchSupplier` (same contract as the ⌘K palette). Without it, the palette still offers navigation and recents. - **Recent screens** are remembered per app in the browser (`localStorage`), most-recent-first. ## Chromeless: replacing the app bar To go further and remove the navigation chrome — no header, no menu/tabs, content filling the viewport — use `chromeless`. The command center becomes the **only** way to move around, so `chromeless` implies `commandCenter`: ```java @UI("") @App(chromeless = true) // no app bar; navigate purely through the command center public class FocusedApp { /* ... */ } ``` Use this for immersive, single-surface apps (a console, a kiosk, a focused editor) where a persistent menu would only add noise. ## How it behaves - **Open:** click the FAB, or press `⌘K` / `Ctrl+K` anywhere. - **Empty state:** navigation tiles for every menu screen on the left, a **Recientes** list on the right. - **As you type:** matching screens first, then entity search results grouped by category (each with a short description), with a loading shimmer while the server responds. An **Ask AI** row appears at the top when an assistant is configured. - **Keyboard:** `↑`/`↓` move the selection, `Enter` opens it, `Esc` closes the palette. - **Close:** `Esc`, the ✕ button (bottom-right), or clicking the backdrop. ## Entity search in YAML A data-authored shell feeds the palette's entity search from a REST source instead of a `GlobalSearchSupplier` class: `globalSearch: {source: …}` on its `type: AppShell`, called with `${state.searchText}`. See [App shell as data › Header extras](/define/yaml/app-shell/#header-extras-pickers-actions-inbox-and-search). On Redwood the source feeds the *Ask* palette's entity search the same way. ## Renderers The command center is a single shared, design-system-neutral web component (`mateu-command-center`), so it renders on every shell — Vaadin and Oracle Redwood. On the Vaadin shell, `chromeless` also removes the header/menu; on the other shells the FAB is added over the shell's own chrome. ## Demo The reference admin panel (`demo-admin-panel`, `Home2`) enables `@App(commandCenter = true)` and implements `GlobalSearchSupplier`, so the FAB is available on every screen and its palette searches demo entities. ## Related - [Global search](/ux-patterns/global-search/) — the `GlobalSearchSupplier` contract the palette uses for entity results. - [Navigation & menus](/ux-patterns/navigation/) — the menu the palette flattens. --- # Comment thread URL: https://mateu.io/ux-patterns/comment-thread/ > A discussion thread with nested replies — ticket comments, review threads, activity. **Status:** ✅ Implemented ## Intent Show a conversation — ticket comments, a review thread, an approval discussion — with its reply structure, so who-said-what-in-reply-to-what reads at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `CommentThread` component: a list of `Comment`s, each with an author, avatar, text, timestamp and nested `replies`. Replies are indented under their parent with a connecting rail; nesting is unlimited. ```java @Section("Discussion") Component thread = CommentThread.builder() .comments(List.of( Comment.builder().author("Ada Lovelace").avatar("👩‍💼").timestamp("2h ago") .text("The export button throws a 500 for large datasets.") .replies(List.of( Comment.builder().author("Alan Turing").avatar("🧑‍💻").timestamp("1h ago") .text("Reproduced. It's a timeout on the streaming query.").build())) .build())) .build(); ``` ![Ticket discussion](/images/docs/comment-thread/ticket.png) The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. `avatar` accepts an emoji or an image URL; with neither, the author's initial is shown. ## When to use it Use `CommentThread` to **display a threaded discussion**. It is read-only; to post a comment, pair it with a form/`MessageInput` and re-render. For a flat chronological feed use `Timeline`. Demo: `/comments-demo`. --- # Comparison card URL: https://mateu.io/ux-patterns/comparison-card/ > Two values side by side with a delta chip — period over period, plan vs plan, before and after. **Status:** ✅ Implemented ## Intent Put two values next to each other and make the difference between them read at a glance — this month vs last, actual vs target, two plans, a before/after. The delta between them is the headline, colored by whether it went the right way. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `ComparisonCard` component: an optional `title`, a `leftLabel`/`leftValue` and `rightLabel`/`rightValue`, and a `delta` with a `trend` (`"up"` / `"down"` / `"flat"`). The delta renders as a chip between the two sides — green for `up`, red for `down`, grey for `flat` — with an ▲/▼ marker. ```java @Section("Revenue") Component revenue = ComparisonCard.builder() .title("Revenue") .leftLabel("Last month") .leftValue("€38k") .rightLabel("This month") .rightValue("€48k") .delta("+26%") .trend("up") .build(); ``` ![Revenue comparison](/images/docs/comparison-card/revenue.png) The values are plain strings, so format them however you like (currency, percentages, counts). `trend` drives the color only — pick the direction that means "good/bad" for your metric (e.g. a falling churn rate is a `down` trend). The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. ## When to use it Use a `ComparisonCard` for **exactly two values whose difference is the point**. For a single KPI with a trend badge use `Stat` or `MetricCard`; for many metrics at once use a `Scoreboard` or `Dashboard`; for tiered plans use `PricingTable`. Demo: `/comparison-demo`. --- # Component Communication URL: https://mateu.io/ux-patterns/component-communication/ > Let independent components on a screen react to each other by emitting and subscribing to named custom events. **Status:** ✅ Implemented — `@Emits`, `@SubscribeTo` / `@SubscribesTo`, `SubscriptionSource`, `UICommand.dispatchEvent(...)` ## Intent Let one component announce that something happened and let any other component react to it — without hard-wiring them together or forcing a full-page navigation. ## Problem A dense operational screen is often made of several independent components: a form, a few sections, a sidebar listing, a header. When the user does something in one of them (confirms a check-in, assigns a room, saves a draft), other parts of the screen need to refresh to stay consistent. The blunt fix is to return a navigation (`return theListing;`) so the whole page reloads. That throws away scroll position, collapses open sections, and feels heavy for what is really a small update. Components also have no stable way to find each other — their DOM ids are generated. ## Solution Use the event bus. A component **emits** a named custom event by returning `UICommand.dispatchEvent(...)` from an action; other components **subscribe** to that event name with `@SubscribeTo` and run an action (typically a refresh) when it fires, receiving the event payload as the action parameters. ``` GuestsSection CheckInForm @Emits(name="guests-section") @SubscribeTo(event="checkin-confirmed", confirmCheckin(): action="load", return dispatchEvent("checkin-confirmed", …) ───┐ source=DOCUMENT) │ document (global bus) ────┴──▶ runs load() → refreshes in place ``` Subscriptions choose where they listen via `SubscriptionSource`: - **`DOCUMENT`** (default) — global bus. The listener is attached to `document`, so it reaches sibling and unrelated components anywhere on the page. - **`COMPONENT`** — same global bus, but only reacts to events whose origin matches `from` (the emitter's `@Emits(name=...)`). - **`SELF`** — legacy scope: listens on the component's own element, catching only events that bubble up from its descendants. A raw `@Trigger(type = OnCustomEvent)` is equivalent to this. --- ## Example A guests section confirms a check-in and, instead of navigating to the arrivals listing, emits an event. The surrounding check-in form subscribes and refreshes itself in place. ### Emitter :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @PlainText @Compact @Emits(events = "checkin-confirmed", name = "guests-section") public class GuestsSection { @Hidden String id; @Toolbar @Label("Confirmar check-in") Object confirmCheckin(HttpRequest httpRequest) { var repository = MateuBeanProvider.getBean(ReservationLineRepository.class); return repository.findById(id).map(line -> { line.setStatus(CheckInStatus.CHECKED_IN); repository.save(line); // Announce it on the bus instead of navigating away. return (Object) List.of( Message.success("Check-in confirmado para " + line.getTitular()), UICommand.dispatchEvent("checkin-confirmed", Map.of("reservationId", id))); }).orElse(Message.success("Reservation not found")); } } ``` ### Subscriber ```java @Trigger(type = TriggerType.OnLoad, actionId = "load") // Refresh the whole form in place whenever any component announces a confirmed check-in. @SubscribeTo(event = "checkin-confirmed", action = "load", source = SubscriptionSource.DOCUMENT) public class CheckInForm implements HeaderSupplier { @Hidden String id; public Object load(HttpRequest httpRequest) { return populate() ? (Object) new State(this) : Message.success("Reservation not found"); } private boolean populate() { ... } // re-reads the reservation into the fields // ... fields, sections (including the GuestsSection above), header() ... } ``` ```yaml # src/main/resources/specs/ui/routes.yaml type: Routes routes: - route: checkin/:id # the demo-admin-panel route of this form viewModel: com.example.CheckInForm ``` When the user clicks **Confirmar check-in**, the action persists the change and returns a `dispatchEvent("checkin-confirmed", …)`. The event reaches `document`; `CheckInForm`'s subscription fires its `load` action, which re-reads the reservation and re-renders — no navigation, no lost scroll position. The `reservationId` payload arrives as the `load` action's parameters. ### Filtering by source (`COMPONENT`) To react only to events from a specific component, name the emitter with `@Emits(name=...)` and match it with `from`: ```java @SubscribeTo(event = "checkin-confirmed", action = "load", source = SubscriptionSource.COMPONENT, from = "guests-section") ``` --- ## How it works 1. **Emit** — `UICommand.dispatchEvent(eventName)` / `dispatchEvent(eventName, payload)` returns a `DispatchEvent` command. The frontend (`ConnectedElement.applyCommand`) dispatches a real `bubbles + composed` DOM `CustomEvent` from the emitting component's element, stamping `detail.__source` with the emitter's logical name (`@Emits(name=...)`, falling back to its server-side type) — only on object payloads, so existing events keep their exact shape. 2. **Subscribe** — `@SubscribeTo` maps to an `OnCustomEvent` trigger carrying `source` and `from` (`TriggerMapper`), serialized in the component metadata. `@Emits(name)` is surfaced as `ServerSideComponentDto.emitsName` via `EmitsMapper`. 3. **Listen** — on render, `ComponentElement.registerCustomEventListeners()` attaches a listener on `document` (for `DOCUMENT`/`COMPONENT`) or on the element itself (for `SELF`); they are removed in `disconnectedCallback` to avoid leaks. `customEventManager` filters by event name and, for `COMPONENT`, by `detail.__source === from`, then runs the action server-side passing `event.detail` as parameters. Propagation is only stopped for `SELF` subscriptions so the global bus is never short-circuited. --- ## Master/detail from a grid row selection A common trigger for an event is selecting a row in a grid. Annotate the grid list field with [`@OnRowSelected`](/reference/key-annotations/#onrowselected): when the user clicks a row, Mateu runs the named method on the grid's owner class, auto-injecting the clicked row. The handler emits an event; a sibling/parent component subscribes and updates a detail panel — all without navigating. This works even on **read-only** grids (the usual case for a display table inside a read-only form), which the built-in CRUD detail-edit selection does not. ### Emitter — selecting a guest updates the cardex ```java @PlainText @Compact @Emits(events = {"checkin-confirmed", "pax-selected"}, name = "guests-section") public class GuestsSection { @Label("") @Stereotype(FieldStereotype.grid) @OnRowSelected("onGuestSelected") List<GuestData> guests = new ArrayList<>(); // The clicked GuestData is auto-injected. Object onGuestSelected(GuestData guest, HttpRequest httpRequest) { var pax = new HashMap<String, Object>(); pax.put("lastName", guest.getLastName()); pax.put("firstName", guest.getFirstName()); pax.put("nationality", guest.getNationality()); pax.put("hasCardex", guest.isHasCardex()); // Wrapped in a List so the bare UICommand isn't treated as a page result. return List.of(UICommand.dispatchEvent("pax-selected", pax)); } } ``` ### Subscriber — the cardex reloads *itself* The cleanest subscriber is the cardex **as its own component**, so only it re-renders (not the whole page). Extract the cardex fields into their own class and embed it as an independent component by making it a `MultiView` (here a read-only `AutoEditableView`). A field whose type is a `MultiView` subclass is rendered as an independent embedded `ServerSideComponent` — see [Partial Forms](/ux-patterns/partial-forms/). ```java // The entity the cardex shows. The @SubscribeTo lives HERE (the loaded "model view"), because the // embedded component's triggers are mapped from the loaded entity, not from the orchestrator. @PlainText @Compact @Title("Info cardex") @SubscribeTo(event = "pax-selected", action = "reloadPax", source = SubscriptionSource.DOCUMENT) public class Cardex { @Label("Titular") String fullName; @Label("Email") String email; // … the rest of the cardex fields … } // The cardex as an independent, embedded, read-only component that reloads only itself. @UI("/checkin-cardex") @ReadOnly public class CardexView extends AutoEditableView<Cardex> { private static volatile Cardex selected; // demo holder; survives in-place re-renders private static volatile boolean flip; public static void prime(Cardex c) { selected = c; } @Override public Cardex load(HttpRequest rq) { return selected != null ? selected : new Cardex(); } @Override public void persist(Cardex c, HttpRequest rq) { selected = c; } // Advertise reloadPax so the embedded component CLAIMS it (and routes it to handleAction). @Override public List<Action> actions(HttpRequest rq) { var l = new ArrayList<>(super.actions(rq)); l.add(Action.builder().id("reloadPax").build()); return l; } @Override public Object handleAction(String actionId, HttpRequest rq) { if ("reloadPax".equals(actionId)) { var pax = rq.getParameters(Cardex.class); // the pax-selected payload if (pax != null) selected = pax; // Alternate the (always-view) route so the embedded mediator re-renders every time. flip = !flip; setRouteTo(flip ? "/view" : "/"); return new State(this); } return super.handleAction(actionId, rq); } } ``` Embed it in the page as a plain field; seed the lead on load so it shows data initially: ```java public class CheckInForm { @Section(value = "Info cardex", zone = "left") @Label("") CardexView cardex = new CardexView(); // in load()/populate(): CardexView.prime(line.getGuests().get(0).getCardex()); } ``` Now selecting a guest re-renders **only** the cardex with that pax — the rest of the check-in form, its scroll position and open sections are untouched. ### Three things that make the self-reload work 1. **`@SubscribeTo` on the entity, not the orchestrator** — an embedded `MultiView`'s triggers are mapped from the loaded model (`Cardex`), so the subscription must live there. 2. **Advertise the action** — `reloadPax` must be in the component's `actions()` (alongside the built-in `edit`/`save`/`cancel-edit`), otherwise the dispatched event bubbles unclaimed and never reaches the server. (`@OnRowSelected` registers its action automatically; a custom one on an embedded orchestrator you add by hand.) 3. **Force a re-render** — return `new State(this)` after alternating the (always-view) route. The embedded mediator only re-renders when its route changes, so a fixed `/view` would update on the first selection only; alternating `/view` ↔ `/` (both resolve to the view) re-renders on every selection. ### Simpler alternative — handle it on the page If a dedicated cardex component is overkill, subscribe on the page itself and update an `@Inline` section, returning `new State(this)`. The whole page re-renders (it may reset the active tab/scroll), but it needs no extra component: ```java @SubscribeTo(event = "pax-selected", action = "selectPax", source = SubscriptionSource.DOCUMENT) public class CheckInForm { public Object selectPax(HttpRequest rq) { populate(); clientInfo.applySelectedPax(rq.getParameters(Cardex.class)); return new State(this); } } ``` --- ## Multi-state embedded islands (backend-driven state machines) The same island mechanics scale to an in-page element whose **content the backend decides**, with any number of states. The demo's check-in *Documento* block is an `@Inline` embedded `EditableView` with three states: 1. **Sin datos** — a warning notice plus an *Escanear documento* button. 2. **Hay datos** — a property list with the scanned data and the built-in *Edit* toolbar button. 3. **Editor** — the standard editable form; *Save* persists and lands back on state 2. ```java @UI("/checkin-documento") @Title("Documento") public class DocumentoView extends EditableView<Object, DocumentoEditor> { @Hidden String stayId; // context, seeded by the host (see below) @Hidden boolean vistaAlterna; @Autowired DocumentScanner scanner; private Guest guest() { ... } // the pax of stayId private DocumentoDatos fill(DocumentoDatos d, Guest g) { ... } // copies the scanned data @Override public Object view(HttpRequest rq) { var guest = guest(); if (guest == null || !guest.identityComplete()) { return new DocumentoPendiente(); // state 1 — its class carries } // @SubscribeTo("documento-escaneado") return fill(new DocumentoDatos(), guest); // state 2 — @Section(propertyList = true) } @Override public DocumentoEditor editor(HttpRequest rq) { ... } // state 3 @Override public void save(HttpRequest rq) { ... } // persists, lands back on state 2 @Override public boolean readOnly() { // no Edit button while empty var guest = guest(); return guest == null || !guest.identityComplete(); } @Override public Object handleAction(String actionId, HttpRequest rq) { return switch (actionId) { case "escanear" -> LongTask.create("Escaneando documento…") // SSE progress dialog .withProgressBar() .withCommand(UICommand.dispatchEvent("documento-escaneado")) .run(progress -> scanner.scan(stayId, progress)); case "reloadDocumento" -> { // fired by the subscription vistaAlterna = !vistaAlterna; // route flip → re-render setRouteTo(vistaAlterna ? "/view" : "/"); yield new State(this); } default -> super.handleAction(actionId, rq); }; } } ``` The host page embeds it and passes context by **just setting fields** on the instance — the framework seeds the island's initial state with the field value's simple properties: ```java @Section(value = "Documento", zone = "main") @Inline @Label("") DocumentoView documento; public IdentidadStep load(HttpRequest rq) { stayId = GuestHeaders.idFromRoute(rq, "checkin"); documento = new DocumentoView(); documento.setStayId(stayId); // reaches the island's first render return this; } ``` The moving parts are the same three rules as the cardex above, plus two specific to this shape: the async leg (the scan) is a [`LongTask`](/ux-patterns/long-running-jobs/) SSE action whose completion command dispatches the event, and the `@SubscribeTo` lives on the **empty-state model** (the class `view(...)` returns in state 1), because that is the loaded model while the user can trigger the scan. Because the host is re-created on every request, it must derive its own context (here the id from the route) before seeding the island. --- ## When to use - **Independent components on one screen** that must stay in sync (sections, sidebars, headers). - **In-place refresh** after an action, instead of a full-page navigation. - **Decoupled reactions** — the emitter does not need to know who is listening; the event name is the contract. ## When not to use - A single self-contained form with no peers to notify — just return the updated state. - Strict step ordering — use a [Wizard](/ux-patterns/wizard/) instead. --- ## Principles served - **Workflow over screens** — a local action updates the screen in place instead of bouncing through a navigation. - **Decoupling** — components communicate through named events, not direct references. - **Recoverability** — refreshing in place preserves the user's context (open sections, scroll). ## Related - [`@SubscribeTo` / `@Emits` / `@OnRowSelected` reference](/reference/key-annotations/) - [Partial Forms](/ux-patterns/partial-forms/) --- # Create and edit URL: https://mateu.io/ux-patterns/create-and-edit/ > The Redwood create-and-edit patterns — simple routed forms, advanced multi-section pages, and drawers over the listing. **Status:** ✅ Implemented (as patterns over `AutoCrud`) ## Intent Let users create and edit records with the right amount of ceremony: a plain form for simple entities, a rich multi-section page for complex ones, or a drawer that slides over the listing for quick edits. ## Simple: routed forms `AutoCrud<T>` gives the Redwood **Create and Edit — Simple** template out of the box: `/new` and `/{id}/edit` routed forms with validation, optimistic locking and the dirty guard. No extra code. ## Advanced: sections, zones and tabs The Redwood **Create and Edit — Advanced** template is the same edit form composed for a complex record: grouped sections, multi-column zones and tabbed areas. In Mateu that is a composition of the existing layout vocabulary on the entity's edit form, not a separate archetype: - **`@Section(name, columns)`** on entity fields groups the form into titled sections (add `propertyList = true` for read-only label/value rows). - **`@Zones` + `@Section(zone = ...)`** arranges sections in side-by-side zones (e.g. main content left, summary/audit right). - **Tabs** — a `@Panel`-grouped tab layout or a `TabLayout` in a custom form component for "Details / History / Attachments" areas. - **`@ReadOnly`, `@Help`, `@Stereotype`** fine-tune per-field behavior; bean-validation annotations drive validation. All of it renders with the same anatomy (page header, color strip, footer actions) on every renderer — see the demo classes in `demo/demo-admin-panel` for live examples and [the forms guide](/java-ui-definition/forms/) for the full field/layout vocabulary. ## Drawer: edit over the listing `editInDrawer()` on the crud switches New/Edit to the **Create and Edit — Drawer** template: the form slides over the listing, which never unmounts; saving persists, closes the drawer and re-runs the search in place. See [Drawer](/ux-patterns/drawer/#crud-editing-in-a-drawer-editindrawer) and the `/drawer-crud-demo` showcase page. ![Edit in a drawer over the listing](/images/docs/drawer/edit-in-drawer.png) ## When to use what - Few fields, fast data entry → **Simple** (default `AutoCrud`). - Rich record with grouped content → **Advanced** (`@Section`/`@Zones`/tabs on the same crud). - Quick edits where context matters → **Drawer** (`editInDrawer()`). --- # Dashboard URL: https://mateu.io/ux-patterns/dashboard/ > Give users a prioritized, at-a-glance overview of their essential business status. **Status:** ✅ Implemented ## Intent Give users a landing page that summarises the status of their business at a glance: a band of KPIs on top and a grid of titled panels (charts, lists, notes) below, each one an entry point to more detail. ## Problem Operational users open the app dozens of times a day just to answer "is everything OK?". Forcing them through listings and detail screens to reconstruct that answer wastes time; hand-building a dashboard with raw layouts means re-inventing metric tiles, grid placement and responsive behaviour on every project. ## Solution Extend `Dashboard` and declare fields holding components. Mateu lays them out as a dashboard grid: - Consecutive `MetricCard` fields are grouped into a **scoreboard** band (full-width strip of KPI tiles). - Component fields annotated with `@Panel` become **titled tiles** on a responsive grid (`title` defaults to the field label; `colSpan`/`rowSpan` control the footprint). - Any other component field is placed on the grid as-is. ```java @UI("/dashboard") @Title("Sales dashboard") public class SalesDashboard extends Dashboard { MetricCard revenue = MetricCard.builder() .title("Revenue").value("1.2").unit("M€") .trend(MetricTrend.up).trendLabel("+8% vs last month") .timeframe("This month") .icon("vaadin:dollar") .build(); MetricCard orders = MetricCard.builder() .title("Orders").value("3,421") .trend(MetricTrend.up).trendLabel("+112") .timeframe("Last 7 days") .build(); @Panel(title = "Monthly sales", subtitle = "Units sold per month", colSpan = 2) Chart sales = Chart.builder() .chartType(ChartType.bar) .chartData(ChartData.builder() .labels(List.of("Jan", "Feb", "Mar")) .datasets(List.of(ChartDataset.builder() .label("2026").data(List.of(120d, 190d, 300d)).build())) .build()) .build(); @Panel(title = "Notes") Markdown notes = new Markdown("- Summer campaign starts **July 15th**", null, null); } ``` ![Sales dashboard](/images/docs/dashboard/sales-dashboard.png) Populate the fields in the constructor or field initializers — query your use cases or repositories there, exactly like any other Mateu view-model. Override `columns()` to fix the number of grid columns; the default (`0`) lets the renderer pick a responsive auto-fit count. ### Drill-in Give a `MetricCard` an `actionId` to make it clickable; the action is dispatched to the page like a button press, so you can navigate to the backing listing: ```java MetricCard pending = MetricCard.builder() .title("Pending approvals").value("14") .actionId("openPending") .build(); @Action Object openPending() { return URI.create("/approvals"); } ``` ### Tiles the viewer can rearrange Override `reorderable()` to let each viewer drag the tiles into their own order, the way OPERA Cloud's dashboard works: ```java @Override protected boolean reorderable() { return true; } ``` The viewer drops a tile on another to put it there. From the keyboard, focus a tile and press **Alt+←** or **Alt+→** to move it one place. The order belongs to the viewer: it is kept in the browser for that screen, keyed by each tile's id (the field name), and the declaration order stays the default. A tile you add later shows up after the ones the viewer has already placed. Nothing goes to the server, so a viewer who changes browser starts from the declared order. The flag lives on the grid the archetype composes (`ResponsiveGrid.reorderable`; fluent: `grid.asReorderable()`), so any responsive grid of tiles can offer it. It works on the Vaadin and Redwood renderers. The native renderers keep the declared order. ### Fluent variant Everything is also available as fluent components for `ComponentTreeSupplier` pages: put a `Scoreboard`, `DashboardPanel`s and `MetricCard`s on a `ResponsiveGrid` — the grid the `Dashboard` archetype composes — when the layout is data-dependent. (`DashboardLayout` is deprecated: use `ResponsiveGrid`.) ```java import io.mateu.uidl.data.DashboardPanel; import io.mateu.uidl.data.GridTrack; import io.mateu.uidl.data.ResponsiveGrid; import io.mateu.uidl.data.Scoreboard; import io.mateu.uidl.fluent.Component; import io.mateu.uidl.interfaces.HttpRequest; import java.util.List; @Override public Component component(HttpRequest request) { return new ResponsiveGrid( "dashboard", List.of(), // no tracks = auto-fit; or N × GridTrack.fill() List.of( Scoreboard.builder().metrics(kpis()).build(), DashboardPanel.builder().title("Monthly sales").colSpan(2) .content(salesChart()).build())); } ``` ### Checklist for KPIs A number on a dashboard is only useful if the reader knows what it measures and over which period. Before shipping a dashboard, check that: - **Every metric is named and explained.** Give each `MetricCard` a `title` and a `description` (or a panel subtitle) that says what is counted, so the tile reads without asking anyone. - **Every number carries its timeframe.** Set `timeframe` to the period the value covers, e.g. `MetricCard.builder().title("Revenue").value("12.4k").timeframe("Last 7 days")`. The renderers show it under the value, small and in the secondary text colour, and add it to the tile's accessible name ("Revenue, 12.4k, Last 7 days, …"). A blank timeframe shows nothing. "1,204 orders" without a period is ambiguous; "1,204 orders · This month" is not. - **One date format per locale.** Format the dates in titles, timeframes and panels the same way across the dashboard (format them from the request locale), rather than mixing `07/10`, `Oct 7` and `2026-10-07` on one screen. - **Every listing on the dashboard has a meaningful default sort**, such as most recent first or largest amount first, so the rows that matter are at the top without a click. `timeframe` is **experimental** (`@Experimental`): its name and shape may still change before it is declared stable. To help adoption, Mateu logs a one-time INFO hint when a dashboard's `MetricCard`s carry no timeframe. ## Redwood parameter and slot reference What the Redwood `dashboard-landing-page` template (plus `dashboard-grid`, `dashboard-panel` and `scoreboard`) exposes, and what Mateu gives you for it. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | **Slot** `kpi` | consecutive `MetricCard` fields, grouped into the scoreboard band | ✅ | | `scoreboard.data` | the `MetricCard` fields themselves (or `Scoreboard` in the fluent variant) | ✅ | | `scoreboard.selection` / `selectionMode: none \| single` | `MetricCard.actionId` makes a tile actionable, but a tile cannot hold selected state | 🟡 | | `scoreboard.maxKpis` | — every declared metric renders | — | | `dashboard-panel {panelTitle, panelSubtitle}` | `@Panel(title, subtitle)` / `DashboardPanel` | ✅ | | `dashboard-grid` placement | `@Panel(colSpan, rowSpan)`; `columns()` fixes the column count (`0` = responsive auto-fit) | ✅ | | `displayOptions.scoreboardSticky` | — the band scrolls with the page | — | | `displayOptions.density: standard \| compact` | `@Compact`, set on the view rather than as a template option | 🟡 | | `selectContext` / `selectObject` + `displayOptions.switcherSearch` | `RecordSwitcherSupplier` on a page with a header (the reflected form variant). The `Dashboard` archetype composes its own heading and has no page header, so it cannot carry one | 🟡 | | `editLayoutMode` (drag tiles) | `reorderable()`: each viewer drags the tiles into their own order, kept in their browser | 🟡 | | `contentLibraryData`, `editLayoutOptions {share, properties, contentLibraryFilters}` | ⚪ adding tiles from a content library and sharing layouts are a Fusion Apps concern, out of scope by decision | ⚪ | | `spRestoreDefaults`, `spShare` | ⚪ part of the same edit-layout feature | ⚪ | ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | `Dashboard` archetype (scoreboard band + panels) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `MetricCard.actionId` drill-in | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `MetricCard.timeframe` (under the value + in the accessible name) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `@AutoPage` inference (MetricCard fields → dashboard) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Reorderable tiles | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | The renderer columns of the first three rows need no dashboard code: the archetype is pure composition on the one responsive grid. Tile reordering is client-side (the viewer's own order), built on the web renderers (Vaadin, Redwood) only. ## When to use it Use a dashboard as the **home route** of operational backoffices: the scoreboard answers "is everything OK?" and the panels give one-click access to whatever is not. Prefer `AutoCrud` listings with `@KPI` headers when the overview is about a single collection rather than the whole business. --- # Data management URL: https://mateu.io/ux-patterns/data-management/ > A dense, full-width page that shows the same data as a grid and as a Gantt, with a toolbar switcher between them — the Redwood Data management template. **Status:** ✅ Implemented (Java; .NET/Python ports planned) ## Intent Present a data set two ways — a **data grid** and a **Gantt timeline** — on one dense, full-width page, with a toolbar switcher so the user can review it as a table or as a schedule. The Oracle Redwood **Data management** template. ## How :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `DataManagement` and supply the two views: ```java @UI("/project-plan") @Title("Project plan") public class ProjectPlanBoard extends DataManagement { @Override protected Component gridView(HttpRequest rq) { ... } // the dense table @Override protected Component ganttView(HttpRequest rq) { ... } // the Gantt canvas } ``` - The page lays out **full width** (`PageWidthStyle.FULL_WIDTH`). - A toolbar switcher (two buttons, labels via `gridLabel()`/`ganttLabel()`) flips the active view. - The active view is kept in state (`_view`, `"grid"` by default) and the page **re-renders in place** when the user switches — no navigation. - A heading (from `@Title`) sits above the toolbar; override `heading()` or return blank to omit it. `gridView` is any component — typically a dense table (an embedded crud/listing, a fluent `Grid`, or `@InlineEditing` + `@Compact` for in-place editing); `ganttView` is typically a `Gantt` (the same canvas the `GanttPage` archetype uses). Pure composition of existing components, so it renders on Vaadin and the native renderers without renderer work — **not yet on Redwood**, which renders neither a fluent `Grid` nor a `Gantt` (only the view switcher shows). ## Docked panels The Redwood data-management page docks panels beside and under the content — a details pane next to the grid, a messages or log strip under it. Override `endPanel(rq)` and/or `bottomPanel(rq)`: ```java @Override protected DockedPanel endPanel(HttpRequest rq) { return DockedPanel.builder().id("details").title("Details") .content(detailsOf(selected)).size("24rem").open(true).build(); } @Override protected DockedPanel bottomPanel(HttpRequest rq) { return DockedPanel.builder().id("log").title("Log").content(logOf(rq)).build(); } ``` Each declared panel gets a toggle in the toolbar (and a ✕ in its own header); whether it is open is page state, so toggling re-renders in place. The panels **reflow** the content — the grid or Gantt shrinks to make room (the end panel is a fixed track beside it, stacking under it below 48rem; the bottom panel caps its height at `size`, default `16rem`, and scrolls) — which is the *inner*, modeless variant of the Redwood slots. For an *overlay* panel, return a `Drawer` from an action. ![Docked end and bottom panels](/images/docs/data-management/docked-panels.png) ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | View switcher (grid ⇄ Gantt) | ✅ | ✅ | ✅ | ✅ | 🟡 ¹ | ✅ | ✅ | | Docked end / bottom panels | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ¹ See above: Redwood does not draw the fluent grid/Gantt views yet. ## Redwood parameter and slot reference The real `data-management-page` API is **considerably richer than "grid ⇄ Gantt"**: it is a transactional page with four dockable panels. Mateu covers the view switcher, the full-width canvas and the two reflowing (inner) panels. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | Full-width canvas | `pageWidth()` → `PageWidthStyle.FULL_WIDTH` | ✅ | | View switcher | `gridView`/`ganttView` + `gridLabel()`/`ganttLabel()`; the active view is page state and re-renders in place | ✅ | | Page heading | `heading()` (from `@Title`; return blank to omit) | ✅ | | **Slots** `innerEnd` / `innerBottom` | `endPanel(rq)` / `bottomPanel(rq)` → `DockedPanel` (reflow) | ✅ | | **Slots** `outerEnd` / `outerBottom` | — the overlay variants: return a `Drawer` (`modeless`, any `DrawerPosition`) from an action | 🟡 | | `endOpened` / `bottomOpened: inner \| outer \| none` | `DockedPanel.open` (initial) + the toolbar toggles; open state is page state | ✅ | | `endDisplay` / `bottomDisplay: reflowModeless \| overlayModal` | `Drawer.layout` (reflow) vs `Drawer.modeless` (overlay) express both modes at component level | 🟡 | | `bottomDrawerState: auto \| closed \| maximized \| minimized` + `displayOptions.bottomDrawerMode/Height` | `DrawerPosition.bottom` + `collapsible` + `maximizable` + `DrawerSize` | 🟡 | | Transactional header (`save`/`cancel`) | — this archetype is a viewer; use `AutoCrud` or an advanced create-edit form for the transaction | — | | **Slot** `messages` | toasts/alerts ride on the wire's `messages`, not as a page slot | 🟡 | | **Slot** `search` | the app-level smart search bar / ⌘K palette, not a page slot | 🟡 | | **Slot** `announcement` (aria-live) | `UICommand.announce(text)` from any action | ✅ | | `feedback` + `openFeedback` | ⚪ the embedded survey is a Fusion Apps concern, out of scope by decision | ⚪ | ## Demo `demo-admin-panel/.../datamanagement/DataManagementDemo.java` (`/data-management-demo`): a project plan shown as a table and as a Gantt, switchable from the toolbar. ## See also - [Gantt](/ux-patterns/gantt/) — the Gantt component and the `GanttPage` archetype used as the timeline view. - [Inline editing in listings](/ux-patterns/inline-crud-editing/) and [High-density screens](/ux-patterns/high-density/) — for the dense, editable grid view. --- # Documents and printing URL: https://mateu.io/ux-patterns/documents-and-printing/ > Return an invoice, a registration card or a report from an action — shown in a new tab, downloaded or printed — render it from HTML to PDF, and print the current page without the app chrome. **Status:** 🧪 Experimental (`@Experimental`, documents API 2026-10) ## Intent Business apps produce *documents*: the folio a guest signs, an invoice, a registration card, a monthly report. Not "export this listing" — a document the screen builds, that the user previews, prints or keeps. Mateu **delivers** documents; it does not produce them. You get: 1. an action returns a **`Document`** and the client shows it, downloads it or prints it; 2. **`UICommand.print()`** prints the current page, without menus, toolbars or buttons; 3. a **`DocumentRenderer`** port (HTML in, PDF bytes out) that *your application implements* with the library of its choice — Mateu ships no implementation. ## Returning a document from an action :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @UI("/folio/:id") public class FolioPage { // YOUR DocumentRenderer bean (see "Producing the bytes"); or build the bytes right here DocumentRenderer renderer = MateuBeanProvider.getBean(DocumentRenderer.class); @Toolbar @Label("View invoice") Document invoice() { return Document.pdf("invoice-" + id + ".pdf", renderer.render(html())); // opens in a new tab } @Toolbar @Label("Download") Document download() { return Document.attachment("bookings.csv", "text/csv", csvBytes()); // the browser saves it } @Toolbar @Label("Print folio") Document print() { return Document.pdf("folio.pdf", renderer.render(html())).printed(); // straight to the print dialog } } ``` | Factory / wither | What the user gets | |---|---| | `Document.pdf(name, bytes)` / `Document.inline(name, type, bytes)` | A new tab with the browser's viewer (a PDF previews inline). | | `Document.attachment(name, type, bytes)` / `.downloaded()` | A download, saved under `name`. | | `.printed()` | The document is loaded in a hidden frame and the print dialog opens for it — no tab. | | `Document.lazy(name, type, () -> bytes)` | The bytes are produced **when the browser fetches them**, not while the action runs. Downloaded by default; `.showInline()` to preview. | A `Document` can also travel in a list with other results — `List.of(new Message("Invoice ready"), document)`. `Document`, `DocumentRenderer` and `PageSetup` are in `io.mateu:uidl`, so a framework-agnostic UI module can use them; the renderer implementation lives in your application. ## How the bytes travel | Document | Transport | |---|---| | up to **256 KB** (JVM system property `mateu.documents.inline-max-bytes`; `DocumentStore.InlineMaxBytes` in C#, `documents.inline_max_bytes` in Python) | Inline, base64, inside the action response — one round trip, nothing kept on the server. | | larger, **lazy**, or an **active** type (HTML, SVG, XML, JavaScript — whatever its size: inline content opens as a blob of the app's own origin, where it would run unsandboxed) | Parked on the server; the response carries a URL, `<baseUrl>/mateu/v3/documents/<token>`, that the browser fetches **once**. | Why both: base64 inflates the bytes by a third and the whole response is held in memory on both sides, which is fine for a 40 KB invoice and wrong for a 30 MB report. A URL also lets the browser stream the file into its PDF viewer or its download manager. The download URL is a **capability**, not a session endpoint: a new tab or an `<a download>` cannot carry the bearer token the API calls carry. So the token is 256 random bits, minted only inside the response to an action the user was allowed to run, **single-use**, and valid for **5 minutes** (system property `mateu.documents.ttl-seconds`). An unknown, spent or expired token answers `404`. The response is `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, and an HTML/SVG/XML document shown inline is served with `Content-Security-Policy: sandbox`, so a document built from user data cannot run script on your origin. The file name reaches `Content-Disposition` sanitised (no CR/LF, quotes or path; the exact name as RFC 5987 `filename*`). The endpoint exists on every adapter — Spring MVC, WebFlux, Micronaut, Quarkus, Helidon MP — and on the ASP.NET Core and FastAPI ports. On Spring it is a filter ordered **before** Spring Security, for the reason above; if a gateway in front of the app requires authentication on every path, let `/**/mateu/v3/documents/*` through. :::caution[Several instances] Parked documents live in memory, per JVM / process. Behind a load balancer use sticky sessions, or install a shared store with `DocumentStore.useShared(...)` (Java). Documents that fit inline are unaffected. ::: ## Printing the current page ```java @Toolbar @Label("Print") UICommand print() { return UICommand.print(); } ``` The client opens the browser's print dialog with a print stylesheet that leaves out the app chrome: navigation, header, menus, buttons, floating buttons, overlays, notifications. The same stylesheet applies to the browser's own **Ctrl+P**. Long scrolling areas print in full. - Mark anything else to leave out with the class `mateu-no-print` or `data-mateu-print="hide"`. - Keep a button on paper with `data-mateu-print="show"`. For a printout with its own layout (letterhead, totals, page numbers), return a `Document.printed()` instead — the page and the paper rarely want the same layout. ## Producing the bytes Mateu does not render documents. Build the bytes with any library — directly in the action, or behind the `DocumentRenderer` port so screens depend on an interface rather than on a library: ```java @Component public class PdfBoxRenderer implements DocumentRenderer { // your application's code @Override public byte[] render(String html, PageSetup setup) { try (var pdf = new PDDocument(); var out = new ByteArrayOutputStream()) { var page = new PDPage(PDRectangle.A4); pdf.addPage(page); try (var cs = new PDPageContentStream(pdf, page)) { cs.beginText(); cs.setFont(new PDType1Font(Standard14Fonts.FontName.HELVETICA), 12); cs.newLineAtOffset(50, 780); cs.showText(Jsoup.parse(html).text()); // lay out what your documents need cs.endText(); } pdf.save(out); return out.toByteArray(); } catch (IOException e) { throw new UncheckedIOException(e); } } } ``` `PageSetup` carries the usual layout parameters (A4/Letter, landscape, margins, title, a running header/footer with `{page}`/`{pages}`/`{title}`) so callers can state them without knowing the library; an implementation honours what it can. The demo's `DemoPdfRenderer` (`demo/demo-admin-panel`) is a complete small example with page numbers and an embedded font. Choosing a library — check the licence against your product's: | Library | Licence | Notes | |---|---|---| | Apache PDFBox | Apache-2.0 | Low-level drawing API; you lay out the page yourself. | | JasperReports | LGPL-3.0 | Report designer + templates; strong for tabular reports. | | A template engine (Thymeleaf, FreeMarker, Mustache…) + headless Chromium (e.g. Playwright for Java) | Apache-2.0 (+ the browser) | Full HTML/CSS fidelity; heavy: a browser per server. | | openhtmltopdf | LGPL-2.1 | HTML/CSS 2.1 + paged media to PDF. | | OpenPDF | LGPL-2.1 / MPL-2.0 | A PDF library (iText 4 fork). | | iText 7 | AGPL-3.0 / commercial | Needs a commercial licence for a closed-source app. | ## On every renderer | Renderer | Inline document | Attachment | `printed()` | `UICommand.print()` | |---|---|---|---|---| | Vaadin (web) | New tab (if a popup blocker refuses it: downloaded instead) | Download | Hidden frame + print dialog | Print stylesheet + dialog | | Redwood (VB) | New tab (same fallback) | Download | Hidden frame + print dialog | Print stylesheet + dialog | | React Native | URL: system browser sheet (preview, share, print). Bytes: share sheet (iOS) / the app that opens the type (Android) | Same | Same as inline — print from the sheet | Not available on mobile: announced to the user | | IntelliJ | Temp file opened with the OS viewer | Save dialog | The OS print service for the type, else opened | The rendered panel through the system print dialog | The ports: return a `Document` from an action in **C#** (`Document.Pdf(...)`, `Document.Lazy(...)`, `.Printed()`, `UICommandDto.Print()`) and **Python** (`Document.pdf(...)`, `Document.lazy(...)`, `.printed()`, `UICommand.print()`). The same wire, the same endpoint (`app.MapMateu(...)` / `add_mateu(...)` add it); as in Java, producing the bytes is the application's job. ## Demo `demo/demo-admin-panel` → `/documents-demo`: an invoice previewed, downloaded and printed, a large report fetched by URL, and the page printed without chrome. Its PDFs come from `DemoPdfRenderer`, the demo's own `DocumentRenderer` on Apache PDFBox (a demo dependency, not a Mateu one). --- # Drag rows to a destination URL: https://mateu.io/ux-patterns/drag-to-a-destination/ > Select listing rows, drag them onto a card, a column or a list of destinations, and an action runs with the origin and the destination — moving folio charges between windows, adding items to a cart. **Status:** ✅ Implemented ![Folio charges grouped by window; the window cards on top are the drop zones](/images/docs/drag-to-a-destination/folio-windows.png) ## Intent Some operations are about *moving* things: folio charges from one billing window to another, reservations into a group, items into a cart. A form ("pick the charges, pick the window, press Move") works, but the natural gesture is to drag the rows where they belong — as OPERA Cloud does with folio windows and the Trip Composer. ## Solution Two pieces, independent of each other: :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: - **`@DragRows("type")`** on a listing (a `Listing`, an `AutoCrud`) makes its rows draggable — the selected rows, or the one under the pointer. - **`DropZone`** is a titled area wrapping any content that **accepts** a drag type. Dropping rows of that type on it runs its **`actionId`** with its **`parameters`** plus **`_draggedIds`** (the dragged rows' ids) and **`_dragType`**: the action knows both ends. ```java @UI("/folio-windows") @DragRows("charge") public class FolioWindows implements Listing<ChargeRow>, HeaderSupplier { @Override public boolean selectionEnabled() { return true; } @Override public ListingData<ChargeRow> search(SearchRequest request, HttpRequest rq) { ... } // the folio's charges @Override public List<Component> header(HttpRequest rq) { return List.of(DropZone.builder() .accept("charge").actionId("moveCharges").parameters(Map.of("window", 2)) .title("Window 2").subtitle("Guest (cash)") .content(List.of(new Text("w2", "13.20 € · 1 charge"))) .build()); } // moveCharges reads _draggedIds and window, moves the charges, and returns the page again } ``` Returning the page from the action re-renders it — the zones' totals and the listing's rows, which reload like on opening. ## Where it works - **Vaadin** — `vaadin-grid` row dragging (`rowsDraggable`) and the shared `mateu-drop-zone`. - **Redwood** — JET's own `oj-table` drag and drop (`dnd.drag.rows`); the zone is an atom whose content shows as text lines. The header components of a listing page (`HeaderSupplier`) are drawn above the table. - **IntelliJ plugin** — `JTable` drag with a transfer handler, and a titled panel as the zone. - **React Native** — no drag on touch: with rows selected and a matching zone on screen, a **Move to…** button opens a picker of the zones. - .NET: `[DragRows("charge")]` + `DropZone`; Python: `@drag_rows("charge")` + `DropZone`. The drag type travels as a MIME type (`application/x-mateu-<type>`), so a zone can tell while the drag is still over it — before it may read the data — whether what comes is its kind. Demo: `demo-vb-pms` → Financials → Windows. --- # Drawer URL: https://mateu.io/ux-patterns/drawer/ > Open a secondary form in a side panel that slides over the current page, and return its result to the host. **Status:** ✅ Implemented ## Intent Let an action open another form — an editor, a picker, a detail — in a panel that slides in from the side, without leaving the page underneath. On close, notify the host page so it can refresh itself or receive the result. ## Problem Centered modal dialogs hide the page context and feel heavyweight for quick side tasks. Navigating away to a second page loses the user's place entirely. Dense operational screens (check-in desks, back offices) need "edit this bit" interactions that keep the main record visible. ## How :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Return a `Drawer` from any action method. Its `content` is any component — typically a form: ```java @Toolbar @Label("Editar en drawer") Drawer editContact() { return Drawer.builder() .headerTitle("Editar contacto") .position(DrawerPosition.end) // end (default) or start .width("28rem") .content(new ContactEditDrawerForm()) .build(); } ``` The drawer slides in over a backdrop and closes on the header ✕, on Esc, on a backdrop click, or when an action run from inside it returns a close command. `modeless(true)` drops the backdrop so the page stays interactive. ### Closing with a result `UICommand.closeModal(...)` has three forms: ```java UICommand.closeModal() // just close the topmost overlay UICommand.closeModal("contact-saved") // close + emit an event UICommand.closeModal("contact-saved", payload) // close + emit an event carrying the result ``` The emitted event goes through the standard component-communication bus, so the host page reacts with `@SubscribeTo` — the payload arrives as the action's parameters: ```java @UI("/drawer-demo") @SubscribeTo(event = "contact-saved", action = "load", source = SubscriptionSource.DOCUMENT) public class DrawerDemo { @PlainText String nombre = ContactHolder.nombre; @Action Object load() { nombre = ContactHolder.nombre; return new State(this); // refresh the page in place } } ``` Inside the drawer, the save handler persists and closes in one return: ```java @Override public Object handleAction(String actionId, HttpRequest httpRequest) { if ("save-contact".equals(actionId)) { var edited = httpRequest.getComponentState(ContactData.class); ContactHolder.nombre = edited.nombre; return List.of( Message.success("Contacto guardado"), UICommand.closeModal("contact-saved", Map.of("nombre", edited.nombre))); } return null; } ``` The same `closeModal(eventName, payload)` contract works for `Dialog` too — it closes whichever overlay is topmost. Overlays stack: a drawer can open another drawer (or a dialog), and each close unwinds only the topmost one. ## Demo `demo-admin-panel/.../drawer/DrawerDemo.java` (`/drawer-demo`): a contact card whose toolbar action opens the editor in a right-hand drawer; saving closes it, toasts, and refreshes the card in place. ## Notes - Closing via ✕, Esc or the backdrop emits **no** event — that's the "dismissed without saving" path, and the host is intentionally not disturbed. - Position `start`/`end` maps to the left/right edge. Width accepts any CSS length; the panel caps at 92vw. - Styling is design-system neutral (Lumo CSS variables with fallbacks), so it renders on every web renderer. ## General Drawer — read-only detail (subtitle, sizes, maximize, peer navigation) The same `Drawer` doubles as the Redwood **General Drawer**: extra read-only info about an object without leaving the page. Four header extras enrich it: ```java return Drawer.builder() .headerTitle("Ada Lovelace") .subtitle("Employee #100") .size(DrawerSize.l) // s=464 · m=648 · l=968 · xl=90vw (width overrides) .maximizable(true) // a ⤢ button bumps the drawer one size up (client-side) .peerNav(new PeerNav("Prev", "/staff/1", "Next", "/staff/3")) // ‹ › arrows in the header .content(readOnlyDetails) .build(); ``` - **`size`** picks a standard width; an explicit `width` still overrides it. - **`maximizable`** shows a maximize button that steps the drawer up the size ladder (`s→m→l→xl`) entirely in the frontend — no server round-trip. - **`peerNav`** puts the previous/next-object arrows (the same `PeerNav` used by page headers) in the drawer header; a `null` route disables that side. - **`subtitle`** renders under the title. Ported to .NET (`DrawerSize`, `Drawer { Subtitle, Size, Maximizable, PeerNav }`) and Python (`DrawerSize`, `Drawer(subtitle=…, size=…, maximizable=…, peer_nav=…)`). ## Bottom Drawer (`DrawerPosition.bottom` + `collapsible`) Set `position(DrawerPosition.bottom)` to dock the drawer at the bottom edge, full width — the Redwood **Bottom Drawer**. It slides up instead of in, and its height defaults to half the viewport (`--mateu-drawer-height`, capped at 90vh). Add `collapsible(true)` for the expand/collapse behavior: a ▾/▴ handle in the header shrinks the drawer to just its header strip and expands it back — entirely client-side, no round-trip. ```java return Drawer.builder() .headerTitle("Detalles del pedido") .position(DrawerPosition.bottom) .collapsible(true) .content(orderLines) .build(); ``` Ported to .NET (`DrawerPosition.Bottom`, `Drawer { Collapsible }`) and Python (`DrawerPosition.bottom`, `Drawer(collapsible=…)`). ## Guided Process Drawer (a wizard in a drawer, `EmbeddedView`) The **Guided Process Drawer** pattern runs a short multi-step process inside a drawer — a subflow or a batch action (≤5 steps; a longer process uses the full-page [wizard](/ux-patterns/wizard/)). Return a `Drawer` whose content is a wizard wrapped in **`EmbeddedView`**: ```java @Toolbar Drawer requestAccess() { return Drawer.builder() .headerTitle("Request access") .size(DrawerSize.m) .content(new EmbeddedView(new RequestAccessWizard())) // the wizard, embedded .build(); } ``` `EmbeddedView(view)` embeds a **routed** model view (a `Wizard`, or any `@UI` view or `routes.yaml` route) as an **independent server-side component**: it renders inside the drawer but routes its **own** actions back to itself, so the wizard advances step by step inside the drawer instead of bubbling its Continue/Back to the host. Its state is the view's fields, serialised exactly as a page's are — no getters needed. Demo: `/guided-process-drawer-demo`. A `ModelViewComponent` renders its view as part of the component around it. In a drawer or a dialog that would be the page behind — the form's fields would come up empty and its buttons run on the host — so as the **content of an overlay** a `ModelViewComponent` wrapping a view is embedded the same way, automatically. Outside overlays it keeps rendering inline. The drawer header shows a **step pager** (`2 | 3`) driven live by the embedded wizard's progress — no extra wiring, it appears whenever the embedded wizard uses `@WizardProgress(STEPS)` or `RAIL`. As a subflow surface the Guided Process Drawer is meant for **short** processes (≤ 5 steps); embedding a longer wizard still works but logs a warning suggesting a full-page [wizard](/ux-patterns/wizard/) instead. :::note[How it is drawn] The renderers draw the drawer's wizard as a **generic wizard** — in Redwood, the step train (`oj-train`) with the step's form and its Back / Next buttons inside the drawer — not as Redwood's `oj-sp-guided-process` template. The full-page **Guided Process** (the overview, the lateral step list) is a routed `Wizard` with `@WizardProgress(RAIL)`. ::: ### Batch action (one step per item) The same shape drives a **batch action** — walk the user through a set of selected items, one review step per item, inside the drawer. Reuse a single step type across several step fields (one field = one step) so N items read as N screens without N step classes: ```java @WizardProgress(WizardProgressStyle.STEPS) public class BatchApprovalWizard extends Wizard { public static class ReviewStep implements WizardStep { @PlainText @Label("Requester") public String requester; @PlainText @Label("System") public String system; @Label("Decision") public Decision decision = Decision.APPROVE; public ReviewStep() {} // the state round trip rebuilds steps with it public ReviewStep(String requester, String system) { this.requester = requester; this.system = system; } } public ReviewStep first = new ReviewStep("Ada", "VPN"); public ReviewStep second = new ReviewStep("Bob", "CRM"); public ReviewStep third = new ReviewStep("Cleo", "Wiki"); public DoneStep done; // completion action on the WIZARD class — its button shows on the penultimate step @WizardCompletionAction @Label("Apply decisions") void apply() { done = new DoneStep(); } } ``` The header pager tracks the batch (`1 | 3` → `3 | 3`). Because a Mateu wizard declares its steps as **fields**, the batch size is fixed at authoring time; a batch whose size is only known at runtime is the limit of this pattern — use a full-page Guided Process for a longer or dynamic flow. Demo: `/batch-approval-demo`. ## CRUD editing in a drawer (`editInDrawer()`) For the "Create and Edit - Drawer" pattern (Oracle Redwood's RDS template), you don't need to build the drawer yourself: override `editInDrawer()` on any `AutoCrud` subclass and the crud's **New** button and row clicks open the create/edit form in a drawer sliding over the listing instead of navigating to the `/new` — `/{id}/edit` routes: ```java @UI("/contacts") public class ContactsCrud extends AutoCrud<Contact> { @Override public CrudStore<Contact> store() { return new ContactStore(); // your CrudStore<Contact> } @Override public boolean editInDrawer() { return true; } // optional: @Override public String editDrawerWidth() { return "42rem"; } } ``` The listing never unmounts (scroll, filters and page survive); **Save** persists, closes the drawer and re-runs the listing's search in place (the closing drawer emits a saved event the listing subscribes to); **Cancel**/✕/Esc just close it. In this mode there is no separate read-only view page — a row click goes straight to the edit drawer (on read-only cruds row clicks keep navigating to the view). ![A row click opens the edit form in a drawer over the listing](/images/docs/drawer/edit-in-drawer.png) Demo: `demo-admin-panel/.../drawercrud/ContactsDrawerCrud.java` (`/drawer-crud-demo`). Tests: `EditInDrawerSyncTest`. ### Save and next, and the error banner Two more pieces of the Redwood create-edit drawer, switched through the crud's `display()` (`CrudDisplay`, the tri-state `Toggle` grammar — `on` · `off` · `disabled`): ```java @Override public CrudDisplay display() { return CrudDisplay.defaults().toBuilder() .saveAndNext(Toggle.on) // default off .create(canCreate ? Toggle.on : Toggle.disabled) .delete(Toggle.off) .build(); } ``` - **Save and next** — editing a series row by row: the drawer gets a *Save and next* button; it saves, and the SAME drawer moves on to the next row of the listing (the server re-sends it with the same id, which refreshes the open drawer in place) while the listing refreshes behind it. On the last row it closes like a plain save. The next row comes from `nextIdAfter(currentId, rq)` — by default the row after it in an unfiltered search; override it to follow the user's filters. Label: `saveAndNextLabel()`. - **Error banner** (`errorBanner`, default `on`) — when the save throws, the drawer stays open with the exception's message as a danger banner above the form and the values the user typed, and the message is announced to screen readers. `off` brings back the plain error toast. - `create` / `delete` — the New and Delete buttons; `disabled` shows them inert (and the server refuses them), on top of the capability gates (`canCreate`, `@NotCreatable`…), which still decide whether the affordance exists at all. ![Save and next: the drawer moved on to the next row](/images/docs/drawer/save-and-next.png) ![A failed save keeps the drawer open with an error banner](/images/docs/drawer/error-banner.png) Tests: `CrudDisplaySyncTest`. ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Drawer (sizes, maximize, peer nav, bottom, collapsible) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `editInDrawer()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Save and next | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Error banner on a failed save | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `CrudDisplay` create / delete toggles | ✅ | ✅ ¹ | ✅ | ✅ | ✅ | ✅ | ✅ | What makes save-and-next and the error banner work on a renderer is one rule: a `Drawer` re-sent with the id of an OPEN drawer refreshes it in place (its `initialData` becomes the form's values) instead of stacking a second one. ¹ In .NET the toggles apply to `Crud<T>`; capability listings (`IListing`) do not have them yet. ## Redwood parameter and slot reference Redwood ships **five** drawer templates; one `Drawer` component covers them all in Mateu, so this table is grouped by template. The canonical page-header elements shared by every page template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope ### `general-drawer-template` | Redwood prop / slot | Mateu | | |---|---|---| | `drawerTitle` / `drawerSubtitle` | `headerTitle` / `subtitle` | ✅ | | `drawerSize: sm \| md \| lg \| xl` | `DrawerSize.s \| m \| l \| xl` (464 / 648 / 968 / 90vw); an explicit `width` overrides | ✅ | | `drawerState: auto \| closed \| maximized` | `maximizable` steps the drawer up the size ladder client-side | 🟡 | | `displayOptions.maximize` | `maximizable` | ✅ | | `nextItem` / `previousItem` + `spPrevious` / `spNext` | `peerNav` → `PeerNav` in the drawer header | ✅ | | **Slots** `header` + default | `header` / `content` (plus `footer`, a Mateu addition) | ✅ | | `closeAction` + `spClose` | ✕, Esc and the backdrop close it and emit **no** event by design (the "dismissed without saving" path) | 🟡 | | `displayOptions.header: auto \| tabsOnly` | — | — | | `displayOptions.goToParent` + `spGoToParent` | — | — | | — | `layout` (dock and **push** the content instead of overlaying) and `modeless` are Mateu additions | ✅ | ### `create-edit-drawer-template` | Redwood prop / slot | Mateu | | |---|---|---| | Create/edit form in the drawer | `editInDrawer()` on any `AutoCrud`; the listing never unmounts | ✅ | | `primaryActionType: auto \| create` | derived from whether the row exists | ✅ | | `unsavedChanges` + `spUnsavedChangesDiscard` / `Cancel` | the framework's dirty guard covers it | ✅ | | `spPrimaryActionAndClose` | **Save** persists, closes the drawer and re-runs the listing's search | ✅ | | `spPrimaryActionAndNext` ("save and next" when editing a series over a listing) | `CrudDisplay.saveAndNext` + `nextIdAfter(id, rq)` | ✅ | | `displayErrorMessageBanner` + `errorMessage` (inline error banner on a failed save) | `CrudDisplay.errorBanner` (default on): the drawer is re-sent with a danger banner and the typed values | ✅ | ### `bottom-drawer-template` | Redwood prop / slot | Mateu | | |---|---|---| | Bottom docking | `DrawerPosition.bottom` | ✅ | | `drawerState: … \| minimized` + `displayOptions.drawerMode: fixed \| closable` | `collapsible` | 🟡 | | `displayOptions {title, maximize}` | `headerTitle`, `maximizable` | ✅ | | `discoverability: on \| off` (peeks a tab so users find it) | — | — | | `spBeforeBottomDrawerStateChange` (cancelable) | — | — | ### `guided-process-drawer-template` | Redwood prop / slot | Mateu | | |---|---|---| | A wizard inside a drawer | `EmbeddedView` + `Wizard` — see [Guided Process Drawer](#guided-process-drawer-a-wizard-in-a-drawer-embeddedview); Redwood draws it as a generic wizard (step train), not with this template | 🟡 | | `processTitle`, `steps[]`, `currentStep`, `drawerSize` | from the embedded `Wizard` and the host `Drawer` | ✅ | | `introductionPanel {secondaryText, indexDisplay}` | — | — | | `spSkip`, `spBeforeStepNavigate` | from the embedded `Wizard`: `stepSkippable(step)` and `beforeStepNavigate(from, to, rq)` — see [Wizard](/ux-patterns/wizard/#redwood-parameter-and-slot-reference) | ✅ | | `displayErrorMessageBanner` | — | — | ### `configuration-drawer-template` The fifth drawer (a settings drawer: `drawerTitle/Subtitle`, `primaryAction`, `header` + default slots) has no dedicated Mateu piece, but its whole surface is a subset of the general drawer — build it with `Drawer` directly. ✅ --- # Editable table URL: https://mateu.io/ux-patterns/editable-table/ > Edit a collection's rows directly in the grid cells, without a per-row detail form. **Status:** ✅ Implemented — `@InlineEditing` ## Intent Let users edit a collection — order lines, a price list, a roster, a set of parameters — **directly in the table**, so bulk and tabular editing is fast and stays in one place. ## Problem By default, editing a row of an editable list opens a **separate detail form**: click the row's *Edit* button, a form appears, change one value, save, close, repeat. That round-trip is fine for a rich record with many fields, but it is slow and clumsy for the very common case of a **flat, tabular collection** where the user wants to tweak a few cells across several rows. Every edit costs a modal, a context switch, and several clicks — the *Desktop Denial* of tabular data entry. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the list field with `@InlineEditing`. Each row's cells become editable inputs right in the grid — no detail form, no per-row *Edit* button. The add / remove / reorder toolbar stays. ```java @InlineEditing @Stereotype(FieldStereotype.grid) List<OrderLine> lines; ``` ![Editable table — order lines edited directly in the grid cells](/images/docs/inline-editing.png) ### One editor per type The editor is chosen from each column's real Java type, so every kind of field is editable in place: | Type | Editor | |---|---| | `String` | text field | | `int` / `Integer` / `long` | integer field | | `double` / `BigDecimal` / `@Stereotype(money)` | number field | | `boolean` | checkbox | | `enum` | combo box (the enum constants) | | `LocalDate` / `LocalTime` / `LocalDateTime` | date / time / date-time picker | | `@Lookup` (reference) | combo box with **remote search-as-you-type** — options come from the field's `LookupOptionsSupplier`, the cell stores the id and shows the label | A field marked `@ReadOnly` stays display-only. ### Persistence — no per-cell save Inline edits travel back in the **normal component state**. There is no per-cell round-trip: the edited rows are persisted whenever the enclosing form's next action runs — a save/submit, or any developer action that reads the list. So a `@Toolbar` "Save"/"Total"/"Recalculate" action already sees the up-to-date collection. ## When to use it | Use inline editing | Use the detail form | |---|---| | Flat, tabular rows (few scalar fields each) | Rich rows with many fields, tabs, or validation-heavy sub-forms | | Bulk edits across many rows | Editing one row at a time, carefully | | Spreadsheet-like data entry | A row that is itself a small screen | Inline editing is opt-in and per-field — a page can mix an inline-edited list with a detail-form-edited one. ## Principles served - **Minimize navigation** — edit in place, no modal per row - **Workflow over screens** — the table is the task, not a launchpad to other screens - **Recoverability** — edits live in state until an explicit action persists them --- # Empty states & skeletons URL: https://mateu.io/ux-patterns/empty-states-and-skeletons/ > Friendly placeholders for "nothing here yet" and shimmering loaders while content arrives. **Status:** ✅ Implemented ## Intent Never show the user a blank void: when a collection has no rows yet, explain why and offer the next step; while content is loading, show its shape instead of a spinner. ## Empty states :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Listings and grids render a friendly empty-state block automatically when they have no rows — set `emptyStateMessage` on the fluent `Listing` (or leave the default). For custom screens, use the `EmptyState` component: ```java @Section("Bookings") Component empty = EmptyState.builder() .icon("📭") .title("No bookings yet") .description("When you create a booking it will show up here.") .actionId("createBooking") .actionLabel("Create your first booking") .build(); @Action Object createBooking() { return URI.create("/bookings/new"); } ``` The call-to-action dispatches the standard action mechanism — same contract as buttons and metric cards. ## Skeletons `Skeleton` renders a shimmering placeholder that mimics the shape of the loading content. Variants: `text` (lines), `card` (a tile), `grid` (table rows), `form` (label + field pairs); `count` repeats the shape. ```java Component loading = new HorizontalLayout( Skeleton.builder().variant(SkeletonVariant.form).count(3).build(), Skeleton.builder().variant(SkeletonVariant.grid).count(5).build()); ``` ![Empty states and skeletons](/images/docs/empty-states/empty-skeleton-demo.png) Use skeletons in place of content that arrives late — e.g. as the initial value of a component field that an `OnLoad` action replaces (`return new State(this)` with the real component once loaded). ## When to use it Show an **empty state** whenever "no results" is a normal situation (fresh accounts, filtered lists) — always say what the user can do next. Show a **skeleton** when you know content is coming and its shape matters; keep the built-in loader overlay for short, unpredictable waits. --- # Entity header URL: https://mateu.io/ux-patterns/entity-header/ > A persistent context banner — identity, key facts and one highlighted metric of the entity a flow operates on. **Status:** ✅ Implemented ## Intent Keep the *who/what* of a flow always in sight — the guest of a check-in, the customer of a case, the order of a fulfilment screen — as a compact banner with the identity, a few key facts and one highlighted metric, so the operator never loses context while working through the steps below. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `EntityHeader` component: a `title` with `badges` (badge-palette `Chip`s), a `subtitle` line, a list of `Fact`s (label-over-value pairs) and an optional right-side metric (`metricLabel` / `metricValue` / `metricCaption`) rendered big in the accent color. ```java @Section("Guest") Component guest = EntityHeader.builder() .title("María Fernández") .badges(List.of(Chip.builder().label("PLATINUM").color("contrast").build())) .subtitle("Ocean Suite · 30 Apr → 07 May · 7N · 2pax · All Inclusive") .facts(List.of( Fact.builder().label("TOTAL RESERVA").value("€ 4.890,00").build(), Fact.builder().label("AGENCIA").value("TUI Group · TUI Magic Life").build())) .metricLabel("FIDELIDAD").metricValue("48.500").metricCaption("23 estancias") .build(); ``` ![Entity header](/images/docs/entity-header/entity-header.png) The banner itself is display-only. The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. ### A fact with an action A single fact can carry an action — e.g. a pencil right after the company a stay is billed to, which opens a drawer to choose or change it. Give the `Fact` an `actionId` (and, optionally, `parameters`, an `icon` and an `actionLabel`): ```java Fact.builder() .label("EMPRESA") .value("Acme Corporation Ltd") .actionId("changeCompany") // the action the button dispatches .actionLabel("Cambiar empresa") // accessible name and tooltip (default: the fact's label) .parameters(Map.of("stayId", stayId)) // sent with the action, like a Button's .build() // icon: a pencil unless you set .icon("vaadin:...") ``` The renderers draw a compact icon-only button immediately after the value, on the same line. Clicking it dispatches `actionId` with `parameters` exactly like a `Button` with that `actionId` does, so it reaches the action method (or the `handleAction(actionId, …)`) of the view that owns the header — a public method with that name is advertised automatically, as with any [action referenced by a component](/java-ui-definition/annotations/actions/#actions-referenced-by-components). When the page hoists its leading `EntityHeader` into the page header (Vaadin, and Redwood's `oj-sp` header), the button travels with the fact. A fact without `actionId` is unchanged: just its label and value, on the wire too. The ports spell it the same way: C# `new Fact { Label = "EMPRESA", Value = "…", ActionId = "changeCompany", ActionLabel = "Cambiar empresa", Parameters = … }`, Python `Fact(label="EMPRESA", value="…", action_id="changeCompany", action_label="Cambiar empresa", parameters={…})`. ## When to use it Use an `EntityHeader` at the **top of a task screen or wizard** so the entity being worked on stays pinned while the user moves through steps — e.g. the guest card above a check-in wizard. For a full record page with tabs, use the [Item Overview](/ux-patterns/item-overview/) archetype instead; for a standalone KPI use [Stat](/ux-patterns/stat/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/entity-header-demo`. --- # Entity Picker URL: https://mateu.io/ux-patterns/entity-picker/ > Select relationships and manage child collections without leaving the form. **Status:** ✅ Implemented — `@Lookup`, `@Searchable` (`@Composition`: declared, not rendered yet — see below) ## Intent Select related entities and manage child collections without leaving the form. ## Problem Picking a customer from thousands, or managing order lines inline, typically pushes the user to another screen and breaks the form in progress. The user loses context and must navigate back. ## Solution ### Selecting a relation — `@Lookup` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use `@Lookup` when a field references a single entity and a simple filterable dropdown is enough. ```java public class Order { @Lookup(search = CustomerLookup.class, label = CustomerLabel.class) private String customerId; } public class CustomerLookup implements LookupOptionsSupplier { @Override public ListingData<Option> search(String fieldName, String searchText, Pageable pageable, HttpRequest httpRequest) { return ListingData.of(customerRepo.search(searchText) .map(c -> new Option(c.getId(), c.getFullName())) .toList()); } } ``` The field renders as an incremental-search input with results inline — no modal, no navigation. ### Selecting via a full search screen — `@Searchable` Use `@Searchable` when selecting the entity requires a richer experience: a listing with multiple columns, filter fields, row actions, or even inline CRUD to create new records before selecting them. Clicking the "Search" button opens the selector class in a modal. When the user clicks a row, the modal closes and the field is updated. ```java public class BookingForm { @Searchable(selector = HotelSelector.class, label = HotelSelector.class) @NotEmpty String hotelId; } ``` The selector class implements [`Listing`](/java-user-manual/build/capability-listings/) and `Selector` (and optionally `LookupLabelSupplier`): ```java @Trigger(type = TriggerType.OnLoad, actionId = "search") @Style("min-width: 40rem;") public class HotelSelector implements Listing<Row>, Searchable, Selector<String>, LookupLabelSupplier { private String _fieldId; @Override public String fieldId() { return _fieldId; } @Override public Selector withFieldId(String fieldId) { _fieldId = fieldId; return this; } @Override public ListingData<Row> search(SearchRequest request, HttpRequest httpRequest) { return ListingData.of( hotels.stream() .filter(h -> h.name().contains(request.searchText())) .toList() ); } @Override public SelectedItem<String> selected(HttpRequest httpRequest) { Row row = httpRequest.getClickedRow(rowClass()); return new SelectedItem<>(row.id(), row.name()); } @Override public String label(String fieldName, Object id, HttpRequest httpRequest) { return hotels.stream() .filter(h -> h.id().equals(id)) .findFirst().orElseThrow().name(); } } ``` ### Inline child collection — `@Composition` `@Composition` declares a field holding a collection of owned child records, created and deleted within the parent form. > **Not rendered yet.** The store-backed child CRUD `@Composition` declares is not implemented: a > `@Composition` field renders nothing (Mateu logs a warning naming it once). To show and edit child > records inside the parent form today, use a plain `List<Child>` field — it renders as an editable > grid whose rows travel in the form's state — or embed the children's own CRUD as an embedded > orchestrator field. ```java public class Order { @Composition( targetClass = OrderLine.class, repositoryClass = OrderLineRepository.class, foreignKeyField = "orderId" ) private List<OrderLine> lines; } ``` ## Structure ``` Order form Customer [Acme Corp ×] ← @Lookup: incremental search inline Hotel [Hotel Paris] [Search] ← @Searchable: opens modal listing Date [2024-03-15] Lines ┌──────────────────────────────┐ │ Product Qty Price │ │ Widget A 2 19.99 │ │ Widget B 1 34.50 │ │ [+ Add] │ └──────────────────────────────┘ [Save] ``` ## Choosing between `@Lookup` and `@Searchable` | | `@Lookup` | `@Searchable` | |---|---|---| | UI | Inline dropdown | "Search" button → modal | | Selector | `LookupOptionsSupplier` | `Listing` + `Selector` | ## Known gaps - **Individually disabled options**: `Option` has no `disabled` flag, so a lookup cannot show a choice as visible-but-unselectable (e.g. an inactive agency). Workarounds: filter it out of the supplier, or mark it in the label (`"ACME (inactive)"`) and enforce the rule server-side in the use case. ## Tree selectors A selector can present its rows as a **tree**: override `gridLayout()` to return `GridLayout.tree` and give the row record a self-referential `children` list. The lookup dialog then shows the hierarchy with expand/collapse carets and a per-row *Select* action — clicking *Select* on any node picks it (`selected()` receives the clicked row as usual). ```java public class ZoneSelector implements Listing<ZoneRow>, Searchable, Selector<String>, LookupLabelSupplier { public record ZoneRow(String id, String name, List<ZoneRow> children) {} @Override public GridLayout gridLayout() { return GridLayout.tree; } ... } ``` For an INLINE tree dropdown (no dialog), see `@TreeSelect`: the field's options carry `children` (supplied by the view's `OptionsSupplier`) and the dropdown unfolds the hierarchy in place, with `leavesOnly = true` restricting selection to leaf nodes. | Best for | Simple option lists | Complex grids, filters, row actions, CRUD | ## Principles served - **Preserve context** — no navigation break, the form stays open - **Minimize navigation** — relation management happens inline --- # FAQ URL: https://mateu.io/ux-patterns/faq/ > A collapsible list of questions and answers — a help section, a support page. **Status:** ✅ Implemented ## Intent Answer common questions compactly — a help section, a pricing-page FAQ, a support article — as a list of collapsible question/answer rows, so the page stays scannable and the reader expands only what they need. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Faq` component: a list of `FaqItem`s (question, answer, and an `open` flag that starts a row expanded). Expanding and collapsing is client-side — no server round-trip. ```java @Section("Frequently asked questions") Component faq = Faq.builder() .items(List.of( FaqItem.builder().question("Do I need to write any JavaScript?") .answer("No. You annotate Java classes and Mateu generates the full UI.") .open(true).build(), FaqItem.builder().question("Which frameworks are supported?") .answer("Spring MVC, WebFlux, Micronaut, Quarkus and Helidon.").build())) .build(); ``` ![Help FAQ](/images/docs/faq/help.png) The renderer is dependency-free, themes through the standard CSS variables and works in dark mode; the chevron rotates as a row opens. ## When to use it Use `Faq` for **question/answer help content**. For arbitrary collapsible sections use `AccordionLayout`; for a timeline of events use `Timeline`. Demo: `/faq-demo`. --- # Feature grid URL: https://mateu.io/ux-patterns/feature-grid/ > A responsive grid of icon + title + description cards — a landing page's feature section. **Status:** ✅ Implemented ## Intent Show a set of features, benefits or capabilities as a scannable grid of icon + title + description cards — the classic "features" band of a landing or product page. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `FeatureGrid` component: a list of `Feature`s (icon, title, description) and an optional `columns` count (0 = auto-fit to the viewport). A feature with an `actionId` becomes clickable. ```java @Section("Features") Component features = FeatureGrid.builder() .columns(3) .features(List.of( Feature.builder().icon("⚡").title("Zero frontend") .description("Annotate Java, get a full web UI.").build(), Feature.builder().icon("🧩").title("Full-stack components") .description("Dashboards, kanban, calendars, charts.").build(), Feature.builder().icon("🤖").title("AI chat") .description("Drop-in assistant that can operate your app.") .actionId("openAi").build())) .build(); ``` ![Product features](/images/docs/feature-grid/features.png) The renderer is dependency-free (CSS grid), reflows to fewer columns on narrow viewports, themes through the standard CSS variables and works in dark mode. On mobile (React Native) and the IntelliJ plugin the cards stack vertically. ## When to use it Use a `FeatureGrid` for **marketing/overview feature bands**. For KPIs use `Stat`/`MetricCard`; for a comparison table use `PricingTable`. Demo: `/features-demo`. --- # File list URL: https://mateu.io/ux-patterns/file-list/ > A list of attachments with type icons, sizes and download links. **Status:** ✅ Implemented ## Intent Show a set of attached files — a ticket's attachments, a record's documents, an export bundle — as a compact list with a type icon, name, size and a download/open action. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `FileList` component: a list of `FileItem`s (name, size label, type, and a `url` and/or `actionId`). The `type` (e.g. `"pdf"`, `"image"`, `"excel"`, `"zip"`, `"video"`) picks the icon. A file with a `url` renders as a download link; one with an `actionId` dispatches the standard `action-requested` event (e.g. to preview it). ```java @Section("Files") Component files = FileList.builder() .files(List.of( FileItem.builder().name("Q3-report.pdf").size("2.4 MB").type("pdf").url("/dl/q3").build(), FileItem.builder().name("brand-logo.png").size("120 KB").type("image").url("/dl/logo").build(), FileItem.builder().name("demo.mp4").size("64 MB").type("video").actionId("preview").build())) .build(); ``` ![Attachments](/images/docs/file-list/attachments.png) The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. ## When to use it Use a `FileList` to **display attachments**. To let the user *add* files, pair it with the chat's upload button or an `@UploadableImage`/file field. Demo: `/filelist-demo`. --- # Filters & Listing URL: https://mateu.io/ux-patterns/filters-and-listing/ > Locate and operate on records with minimal effort. **Status:** ✅ Implemented ## Intent Locate and operate on records with minimal effort. ## Problem A listing without live filters, row actions, and bulk actions forces users to navigate to each record individually to do anything. High-volume workflows become impractical. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `AutoCrud<T>` (or implement `Listing<Row>`) for the collection — no annotation is needed on the collection class —, mark filter fields with `@Filterable`, use a `ColumnActionGroup` column on the row for per-row actions, and `@ListToolbarButton` for bulk actions. Column display is controlled with `@ColumnWidth` and `@HiddenInList`. ```java @UI("/products") public class ProductsListing extends AutoCrud<Product> { @Override public CrudStore<Product> store() { return new ProductStore(); // your CrudStore<Product> } @ListToolbarButton(rowsSelectedRequired = true, confirmationRequired = true) public void deactivateSelected(List<Product> selected) { selected.forEach(p -> { p.setActive(false); store().save(p); }); } } class Product implements Identifiable { String id; String name; boolean active; @Override public String id() { return id; } void setActive(boolean active) { this.active = active; } } ``` ```java public class Product { @Filterable private String name; @Filterable private ProductCategory category; @HiddenInList private String internalNotes; @ColumnWidth("80px") private boolean active; } ``` ![Listing with the smart search bar: status, date-range and price-range chips applied](/images/docs/ux-patterns/filters.png) ## The smart search bar Filters render as a **single search field** (after the Redwood Smart Search pattern), not as a row of inputs. The one field hosts both the free-text keyword search and the structured filters: - **Type and press Enter** to apply a keyword search (matched against `SearchableText.searchableText()` or `toString()`). Several words search for rows containing **all of them**, case-insensitively and in any order — "13 producto" finds "Producto 13". - **Click the field** to open the *Filter by* panel listing every filter. Picking one opens a type-specific widget. Filters already set show their current condition next to their name. - **Every applied condition becomes a chip** in the bar with its own ✕. Adding or removing a chip re-runs the search immediately, so conditions compose (e.g. keyword + status + a date range). - **Clear filters** at the bottom of the panel resets everything at once. ![The Filter by panel, opened by clicking the search field](/images/docs/ux-patterns/filters-panel.png) Which fields become filters is decided server-side: every basic field **and every enum** of the filters class — plus the explicit typed filter fields (`DateRange`, `NumberRange`, `Set<SomeEnum>`, see [below](#typed-filters-on-declarative-listings)). The widget (and the condition semantics) follow the field's type: | Field type | Widget | Condition | State / URL keys | |---|---|---|---| | String | text input + Apply | contains (case-insensitive) | `name=widget` | | Boolean | Yes / No | equality | `certified=true` | | Enum | **multi-select** (checkable options) | IN — any of the picked values | `status=Available,OutOfStock` | | Date/time (`LocalDate`, `LocalDateTime`, `LocalTime`) | **from–to range** | between / ≥ / ≤ | `added_from=2026-01-15&added_to=2026-02-28` | | Number with `@RangeFilter` | **min–max range** | between / ≥ / ≤ | `price_from=100&price_to=150` | | Number (plain) | number input + Apply | equality | `units=5` | ![The date-range widget of a temporal filter](/images/docs/ux-patterns/filters-range.png) Temporal filters are ranges **by default** (equality on an exact instant is almost never what a user wants); numeric ranges are opt-in via `@RangeFilter` on the entity field; enums are multi-selects by default (picking a single value behaves exactly like equality). Because every condition lives in flat state keys, the URL keeps capturing the full listing state — bookmarks and shared links restore ranges and multi-selections too. There is nothing to configure on the frontend — every renderer that ships the shared filter bar (Vaadin) gets this UX, and the Redwood renderer implements the same pattern with its own design system. ## Structure ``` ┌──────────────────────────────────────────────────────────────┐ │ 🔍 (Text: widget ✕) (Category: Electronics ✕) [type here…] │ │ ┌─ FILTER BY ──────────────┐ │ │ │ Name │ │ │ │ Category Electronics │ │ │ │ Active │ │ │ │ Clear filters │ │ │ └──────────────────────────┘ │ ├──────────────────────────────────────────────────────────────┤ │ ☐ Name Category Active [Actions] │ │ ☑ Product A Electronics ✓ [Edit] [▼] │ │ ☑ Product B Clothing ✓ [Edit] [▼] │ │ ☐ Product C Electronics ✗ [Edit] [▼] │ ├──────────────────────────────────────────────────────────────┤ │ [Deactivate selected] [New] [Export PDF] [Excel] [CSV] │ └──────────────────────────────────────────────────────────────┘ ``` Clicking anywhere on a row of a navigable listing opens the record; the checkbox, inline editors and the action/button columns keep their own click. See [the whole row opens the record](/java-user-manual/build/capability-listings/#the-whole-row-opens-the-record). ## Filtering on the default repository You don't need to override anything for the filters to work: the default in-memory `CrudStore.find` applies them. Two mechanisms cooperate: - **Equality filters travel inside the entity-shaped example object** (query by example). A filter counts as **set** when its value differs from a freshly-constructed instance of the filters class, so field initializers and primitive zeros/falses don't filter on their own. Strings match by case-insensitive containment, everything else by equality. The flip side: filtering **by** a field's default value (e.g. an initializer like `status = AVAILABLE`) needs an overridden `find`. - **Ranges and multi-selects travel as `FilterCriterion` entries** (between/gte/lte/in, values already coerced to the field's type) — an entity instance simply has no room for "between 10 and 50" or "any of A, B". They reach the repository through the 4-arg `find(searchText, filters, criteria, pageable)` overload, whose default evaluates them in memory. See [CrudStore](/java-ui-definition/interfaces/crud-store/) for pushing both to the database. ## Typed filters on declarative listings The table above describes the **AutoCrud** path, where the entity doubles as the filters class and Mateu infers the widgets. A [capability listing](/java-user-manual/build/capability-listings/) declaring `Filterable<Filters>` has its own Filters class — there the richer widgets are **opt-in by type**: declare the field as `DateRange`, `NumberRange` (both in `io.mateu.uidl.data`) or `Set<SomeEnum>` and it renders as a from–to range or a multi-select, on any listing: ```java @Data public class BookingsFilters { @Label("Created") DateRange created; // from–to date widget @Label("Total") NumberRange total; // min–max number widget @Label("Channel") Set<Channel> channels; // multi-select with the enum's options } @UI("/bookings") public class BookingsListing implements Listing<BookingRow>, Searchable, Filterable<BookingsFilters> { @Override public ListingData<BookingRow> search(SearchRequest request, HttpRequest httpRequest) { // filters(request) arrives fully typed — apply it however your data source needs var filters = filters(request); var rows = bookings.stream() .filter(b -> filters.getCreated() == null || filters.getCreated().contains(b.created())) .filter(b -> filters.getTotal() == null || filters.getTotal().contains(b.total())) .filter(b -> filters.getChannels() == null || filters.getChannels().isEmpty() || filters.getChannels().contains(b.channel())) .toList(); return ListingData.from(rows); } } ``` On the wire the conditions still travel as flat state keys (`created_from=…&created_to=…`, `channels=WEB,PHONE`), so URL sync, bookmarks and shared links keep working; before your `search(...)` runs they are assembled back into the typed instances (`FilterStateAssembler`), with open bounds as nulls. `DateRange`/`NumberRange` bring `contains(...)` and `isEmpty()` helpers for in-memory application; against a database, translate the bounds into the query. Fields of other types keep the classic single-value widgets. ## Export Override `pdfExportable()`, `excelExportable()`, or `csvExportable()` in your `Listing` class to show the corresponding export button. The framework reuses `search()` with the active filters to collect the data — no extra code needed. ```java public class ProductsListing implements Listing<ProductRow>, Searchable, Filterable<ProductFilters> { @Override public boolean excelExportable() { return true; } @Override public boolean csvExportable() { return true; } @Override public ListingData<ProductRow> search(SearchRequest request, HttpRequest httpRequest) { ... } } ``` Mateu decides what is exported (the whole filtered result set, the visible columns) and delivers the file; **writing** it is your application's job. CSV works out of the box (core carries a dependency-free CSV writer). Excel and PDF need a `ListingExporter` bean of yours, written with the library you choose — until one is registered the Excel / PDF buttons are simply not offered, so there are no dead buttons. See [Export engines](/java-ui-definition/interfaces/listing/#export-engines) for the port and two implementations to copy (Apache POI, Apache PDFBox). ## URL sync and saved views Every time the user triggers a search, the listing updates the browser URL as query parameters. On page load the framework reads those parameters, pre-populates the fields, and triggers the search automatically. The URL captures the full listing state: | Parameter | What it stores | |---|---| | Filter field names | The value of each filter field (e.g. `name=widget`; a multi-select comma-joined, `status=Pending,Cancelled`; a range as `<field>_from` / `<field>_to`) | | `searchText` | The free-text search box value (a hand-written link may use `q` instead) | | `ids` | The framework's **id-set filter**: exactly these rows (e.g. `ids=4MBZS7,JXD3G6`) — see below | | `page` | Current page number (omitted when 0) | | `sort` | Active sort as `field:direction` pairs (e.g. `sort=name:ascending,date:descending`) | ``` /products?name=widget&category=Electronics&page=2&sort=name:ascending ``` This gives three capabilities for free: - **Saved views** — bookmark any filtered URL; opening it restores filters, page, and sort. - **Shareable links** — paste the URL in a chat or email; the recipient lands with the same state. - **Browser history** — the back button returns to the previous filter state. No server-side persistence of views is needed. The browser's native bookmark manager is the saved-views feature. Whatever opens the listing — a pasted link, the menu, the chat assistant — the URL wins: reaching a listing that is already on screen with another query (`/bookings` → `/bookings?status=Cancelled`) applies exactly the new query, and URL filters show as normal removable chips. ### The id-set filter (`?ids=…`) `ids` works on **every** listing without declaring anything: `/bookings?ids=4MBZS7,JXD3G6` shows exactly those two rows, with a removable «Selection: 4MBZS7, JXD3G6» chip («N selected items» beyond three). It is how a link — or an assistant that found some records with its tools, by any criterion the listing has no filter for — shows a concrete set of records in their listing. It combines with the declared filters and the search text. - **AutoCrud / CrudStore**: applied by the store, as an `in` criterion on the row's id field. - **Hand-written `search`**: read it from `request.ids()` (empty when not set) and narrow your query (`WHERE id IN (:ids)`). If you don't, the framework narrows the page your search returned to those ids — exact only when they all fit in that page, so honour it in the query for large listings. ### What the menu says about each listing A menu entry that opens a listing carries a `listing` descriptor: its row id field, the `ids` param, the search param and each declared filter as the query param it reads (type, enum values, range bounds). The chat sends it in its menu context, so the assistant can open a listing already narrowed instead of only the bare screen. ## Known gaps - **Segmented filter tabs with counts** ("All / Waiting queue (3)"): there is no declarative annotation for preset filter tabs over a listing. `@MainFilter` only highlights one search field. Saved views cover the preset part (named condition sets, no live counts); otherwise emulate with a filter field (enum or boolean), or with `TaskQueue`/`QueueGroup` when the grouped-queue shape fits. (Row grouping by parent used to be listed here — it is now first-class: `@GroupBy` on a row field renders group subtotal rows, and `@Aggregate` adds per-group and whole-set totals.) ## Principles served - **Workflow over screens** — act on data without leaving the list - **Keyboard-first** — filters respond to Enter (the listing's `searchOnEnter`, on by default) - **Recoverability** — filter state, page, and sort survive navigation via URL sync; no Filter Amnesia --- # Foldout URL: https://mateu.io/ux-patterns/foldout/ > Show a record overview beside fold-out panels with categories of associated information. **Status:** ✅ Implemented ## Intent Show everything about one business object on a single screen: a fixed overview panel with the record's key information, plus two or more lateral panels — payments, history, notes… — that the user folds in and out as needed. ## Problem Object pages with many categories of associated information usually hide them behind tabs, so the user can only see one category at a time and loses the record context while switching. Long vertical pages bury the categories below the fold instead. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `Foldout`. The first component field is the **overview** (always visible, left); each component field annotated with `@Panel` becomes a **fold-out panel**. Closed panels render as a narrow strip with the rotated title; clicking a strip folds the panel out, and several panels can be open side by side (the row scrolls horizontally when it overflows). ```java @UI("/booking/:id") @Title("Booking 2026-08117") public class BookingFoldout extends Foldout { Markdown overview = new Markdown(""" ### Booking 2026-08117 **Guest:** Jane Smith **Dates:** 12–19 Aug 2026 """, null, null); @Panel(title = "Payments", subtitle = "Charges and refunds") Markdown payments = new Markdown("...", null, null); @Panel(title = "Occupancy") Chart occupancy = Chart.builder().chartType(ChartType.line) /* … */ .build(); @Panel(title = "Notes", open = false) // starts folded Markdown notes = new Markdown("...", null, null); } ``` ![Booking foldout](/images/docs/foldout/booking-foldout.png) `@Panel` attributes on foldout pages: `title` (defaults to the field label), `subtitle`, `icon`, and `open` (initial state, default `true`). ### Fluent variant Build a `FoldoutLayout` directly from `ComponentTreeSupplier` when panels are data-dependent: ```java @Override public Component component(HttpRequest request) { return FoldoutLayout.builder() .overview(overviewCard()) .panels(List.of( FoldoutPanel.builder().title("Payments").width("40rem").content(paymentsGrid()).build(), FoldoutPanel.builder().title("Notes").open(false).content(notes()).build())) .build(); } ``` `FoldoutPanel.width` is an optional CSS length for the **expanded** panel — unset panels keep the renderer's default section width (`--mateu-foldout-panel-flex` / `--mateu-foldout-section-width`, 22rem). Use it to size panels to their content: a wide checklist or grid next to a narrow property list. Two Vaadin-carousel behaviours worth knowing: - The **scroll affordances** (the round left/right buttons at the bottom corners) only appear when the sections genuinely overflow the viewport — a few residual pixels (a scrollbar's width, rounding) don't summon them, and the carousel re-measures as slotted content settles or the window resizes. - The **last fold never renders narrower than the overview column**: a skinny accessory panel (say a 14rem profile strip) widens to match the first fold, so the page reads as balanced columns instead of trailing off into a sliver. ## What a folded panel shows (`summary`) A folded panel is a narrow strip with its rotated title. Give it a **summary** — a count, a status, an amount — so the user can tell whether it is worth opening: ```java @Override protected Component panelSummary(String panelFieldName) { return switch (panelFieldName) { case "payments" -> new Text("payments-summary", "€240 due"); case "requests" -> new Text("requests-summary", "2 open"); default -> null; }; } ``` Fluent: `FoldoutPanel.builder()....summary(component)`. It travels as the child slotted `summary-N` and is drawn in the strip under the title; renderers whose panels never fold (the React Native accordion keeps it under a closed panel's title, IntelliJ under the panel heading) show it as a one-line digest. ![Folded panels showing their summary](/images/docs/foldout/summary.png) ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Overview + fold-out panels, orientation, navigation header | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Folded-panel `summary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ## Redwood parameter and slot reference What the Redwood `foldout-layout` and `foldout-panel` components expose, and what Mateu gives you for them. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope ### Layout (`foldout-layout`) | Redwood prop / slot | Mateu | | |---|---|---| | `orientation: horizontal \| vertical` | `orientation()` → `FoldoutOrientation.vertical` (default: the overview is the first column, left of the panels) \| `horizontal` (the overview is the band across the top — Redwood's `overview` slot — and the panels run below it) | ✅ | | `nextStep` / `previousStep` + `spPrevious` / `spNext` | `navigationHeader()` → `FoldoutNavigation.previousActionId` / `nextActionId` | ✅ | | `displayOptions.goToParent` + `spGoToParent` | `FoldoutNavigation.parentLabel` / `parentActionId` | ✅ | | **Slot** `overview` | the first component field (always visible) | ✅ | | **Slot** default (the panels) | component fields annotated `@Panel`, or `FoldoutLayout.panels` | ✅ | | **Slot** `drilldown` | — | — | | **Slot** `search` | the app-level smart search bar / ⌘K palette, not a page slot | 🟡 | | `selectedPanel` (controlled selection) | `@Panel(open = …)` / `FoldoutPanel.open` set the initial state — the component has no folded state, so an `open = false` panel starts as a strip (title + summary) and selecting it (click, keyboard focus, its page dot) unfolds it; the selection is not a controlled prop afterwards | 🟡 | | `animate` | the renderer animates folding; not configurable | 🟡 | | `displayOptions.bidirectionalNavigation` | on when `FoldoutNavigation.previousActionId` is set (both arrows drawn) | ✅ | | `displayOptions.background: default \| transparent` | — (`style`/`cssClasses` escape hatch) | — | | `displayOptions.inFlowBack` + `spInFlowBack` | — | — | ### Panel (`foldout-panel`) | Redwood prop / slot | Mateu | | |---|---|---| | `panelTitle` | `@Panel(title)` / `FoldoutPanel.title` (defaults to the field label) | ✅ | | — | `subtitle`, `icon`, `width` are Mateu additions with no Redwood equivalent (the Redwood renderer draws `icon` in the panel's top-end corner, beside its title) | ✅ | | **Slot** default | `@Panel` field value / `FoldoutPanel.content` | ✅ | | **Slot** `summary` (what shows on the **collapsed strip**) | `panelSummary(panelFieldName)` / `FoldoutPanel.summary` | ✅ | | **Slot** `recommendation` | — | — | | **Slot** `noData` | — compose an `EmptyState` as the panel content | 🟡 | | `secondaryActions` + `spAction {actionId}` | the overview panel's Edit pencil: `overviewEditActionId()`; other panel-level actions live inside the panel content | 🟡 | ## When to use it Use a foldout for **record workspaces** where the user works one object at a time and hops between its associated categories — reservations, contracts, patient records. Prefer `@Tab` when categories are mutually exclusive and context loss is acceptable, or `MasterDetailView` when the "categories" are really alternative detail parts of a master form. --- # Front-office screens URL: https://mateu.io/ux-patterns/front-office/ > Composing the front-office components into one dense operational screen — queue, context, wizard, folio, monitor. **Status:** Composition — no new primitive needed ## Intent A front-office screen — a hotel reception, a bank branch counter, a service desk — is where an operator works a **queue** of people through **tasks** with money involved. It needs everything at once: who is next, who am I serving, what step am I on, what do I sell, what do I charge, and are the automations behind it healthy. Mateu covers this with a family of high-level components that compose into one dense screen; each is documented on its own page. ## The pieces | Concern | Component | |---|---| | Work queue rail (arrivals / departures / in-house) | [Task queue](/ux-patterns/task-queue/) | | Context banner of the current guest | [Entity header](/ux-patterns/entity-header/) | | Check-in steps | [Wizard](/ux-patterns/wizard/) | | Room assignment | [Resource grid](/ux-patterns/resource-grid/) | | Upgrade offer | [Offer card](/ux-patterns/offer-card/) | | Priced extras | [Add-on picker](/ux-patterns/addon-picker/) | | Side-effects checklist / incidents | [Status list](/ux-patterns/status-list/) | | Pax registered N of M | [Task progress](/ux-patterns/task-progress/) | | Folio breakdown at check-out | [Ledger](/ux-patterns/ledger/) | | Method + charge | [Payment picker](/ux-patterns/payment-picker/) | | Balance vs preauthorization | [Meter](/ux-patterns/meter/) | | Stay-history KPIs | [Stat](/ux-patterns/stat/) | | Automations health | [Process monitor](/ux-patterns/process-monitor/) | ## Structure ``` ┌────────────┬─────────────────────────────────────────────┬──────────────┐ │ TaskQueue │ EntityHeader — María Fernández · PLATINUM │ StatusList │ │ Llegadas ├─────────────────────────────────────────────┤ 🌡 A/C ruido │ │ ▸ 1108 ● │ Wizard: Datos → Habitación → Extras → Firma │ 🔑 Grabar │ │ ▸ 1204 │ TaskProgress pax 1/4 [Añadir pax →] │ ✓ SES auto │ │ Salidas │ ResourceGrid 1201 1204★ 1206 1208 ├──────────────┤ │ ▸ 901 │ OfferCard Master Suite + € 65/noche │ Meter │ │ │ AddOnPicker 🍹 🅿 🕕 Añadidos: € 383 │ ████░ 69% │ │ ├─────────────────────────────────────────────┤ Stat · Stat │ │ │ Ledger € 1.710,50 · PaymentPicker [Cobrar] │ │ ├────────────┴─────────────────────────────────────────────┴──────────────┤ │ ProcessMonitor ● Facturación a Crédito ⚠ 6 [Solucionar] · ● Comercial. │ └──────────────────────────────────────────────────────────────────────────┘ ``` Arrange the panels with the usual layout primitives — `@Zones` for the columns, `@Compact` for density, `@Section(sticky=true)` to pin the queue or the header — exactly like a [Workspace](/ux-patterns/workspace/). The queue's `actionId` loads the selected guest into the central panels ([component communication](/ux-patterns/component-communication/) handles the refresh); the wizard's completion action confirms the check-in. ## Runnable reference app The whole pattern is implemented end to end in `demo/demo-front-office` (Spring Boot MVC, `mvn spring-boot:run`, port 8594): a Check-In work queue feeding a 4-step wizard with a persistent `EntityHeader`, Check-Out with `Ledger` + `PaymentPicker`, an En Casa guest 360 with `Meter`s and a `Stat` history row, and an Automatizaciones board with `Scoreboard` + `ProcessMonitor` — plus a **Modo Staff/Cliente** header selector ([`@AppContext`](/ux-patterns/app-context/)) that re-projects every screen via [`@Audience`](/ux-patterns/audience-projection/). ## Principles served - **Preserve context** — the guest banner and the queue never leave the screen - **Minimize navigation** — check-in, upsell and check-out happen without a page jump - **Workflow over screens** — every panel exists for a step of the operator's job --- # Funnel chart URL: https://mateu.io/ux-patterns/funnel/ > Show conversion through stages — a signup funnel, a sales pipeline, a drop-off analysis. **Status:** ✅ Implemented ## Intent Show how a population shrinks as it moves through stages — visits → signups → paid, leads → deals — so drop-off between steps is obvious. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Funnel` component: one `FunnelStage` per step with a label, a numeric value and an optional bar color. The renderer draws centered bars whose width is proportional to the value and prints the conversion percentage versus the previous stage. ```java @Section("Signup funnel") Component funnel = Funnel.builder() .stages(List.of( FunnelStage.builder().label("Visited").value(12500).color("#3b82f6").build(), FunnelStage.builder().label("Signed up").value(4200).color("#8b5cf6").build(), FunnelStage.builder().label("Activated").value(1800).color("#f59e0b").build(), FunnelStage.builder().label("Paid").value(640).color("#10b981").build())) .build(); ``` ![Conversion funnel](/images/docs/funnel/conversion.png) The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. Each bar shows its value; every stage after the first shows its conversion vs the previous. ## When to use it Use a `Funnel` for **stage-by-stage conversion**. For a value with a trend use a `Stat`; for stages of a *process the user is in* use `ProgressSteps`. Demo: `/funnel-demo`. --- # Gantt / timeline URL: https://mateu.io/ux-patterns/gantt/ > Monitor the progress of a schedule or project on a shared time axis. **Status:** ✅ Implemented ## Intent Show time-based work — a project plan, a shift schedule, a rollout — as bars on a shared time axis, so overlaps, gaps and progress are visible at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Gantt` component: one `GanttTask` per row, with a date span, optional progress (rendered as a fill inside the bar) and optional color. The component derives the axis from the tasks' dates, draws month headers and marks today with a vertical line. ```java @Section("Schedule") Component plan = Gantt.builder() .tasks(List.of( GanttTask.builder().title("Discovery & research") .start(LocalDate.of(2026, 6, 1)).end(LocalDate.of(2026, 6, 12)) .progress(100).build(), GanttTask.builder().title("Implementation") .start(LocalDate.of(2026, 7, 1)).end(LocalDate.of(2026, 8, 14)) .progress(25).build(), GanttTask.builder().title("QA & launch") .start(LocalDate.of(2026, 8, 17)).end(LocalDate.of(2026, 8, 31)) .color("#10b981").build())) .build(); ``` ![Project plan](/images/docs/gantt/project-plan.png) The renderer is dependency-free (plain CSS grid), themes through the standard CSS variables, and works in dark mode. Hovering a bar shows the task's dates and progress. ## When to use it Use a Gantt to **monitor** schedules and communicate plans. It is read-only by design in this version — for interactive re-planning (dragging bars, dependencies), pair it with a form or CRUD that edits the underlying tasks and re-renders. ## Gantt page template (`GanttPage` archetype) For a full-page scheduling canvas — the Redwood **Gantt page** template — extend `GanttPage` instead of embedding a `Gantt` in a form. Implement `tasks(rq)` to supply the bars; the page lays the canvas out **edge to edge** (it declares `PageWidthStyle.EDGE_TO_EDGE`), and an optional `detail(rq)` docks any component (a table, a card) below the canvas as the Redwood bottom panel: ```java @UI("/gantt-page-demo") @Title("Project plan") public class ProjectPlanPage extends GanttPage { @Override protected List<GanttTask> tasks(HttpRequest rq) { ... } // the schedule @Override protected Component detail(HttpRequest rq) { ... } // a summary table } ``` It is pure composition of existing components (Gantt + VerticalLayout + Card), so it renders on Vaadin, Redwood (on `oj-gantt`) and the native renderers without renderer work. Clicking a bar runs `selectGanttTask`, which opens the task's detail in a side drawer (override `taskDrawer`/`taskDetail` to change it). The same archetype exists in the .NET (`GanttPage`) and Python (`GanttPage`) ports. Demo: `/gantt-page-demo`. --- # General overview URL: https://mateu.io/ux-patterns/general-overview/ > A record context switcher over the selected record's overview — the Redwood "General Overview" template as a Mateu archetype. :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The `GeneralOverview<Row>` archetype renders a **context switcher** at the top (a select listing your records) and the **selected record's overview** below, re-rendered in place when the user picks another record — no navigation. ```java @UI("/requisitions") @Title("Requisitions") public class RequisitionOverview extends GeneralOverview<Requisition> { @Autowired RequisitionRepository repo; @Override protected List<Option> switcherOptions(HttpRequest rq) { return repo.findAll().stream().map(r -> new Option(r.id(), r.title())).toList(); } @Override protected Requisition load(String id, HttpRequest rq) { return repo.findById(id); } @Override protected Component overview(Requisition r, HttpRequest rq) { return VerticalLayout.builder().content(List.of( EntityHeader.builder() // the metadata strip: title + badges + facts + metric .title(r.title()) .facts(List.of(Fact.builder().label("Business Unit").value(r.unit()).build())) .metricLabel("Amount").metricValue(r.amount()) .build(), Card.builder().title(new Text("Details")).build() // … the property cards )).build(); } } ``` The first record is selected by default. `emptyOverview()` customizes what shows when nothing is selected, and `recordLabel()` labels the switcher (unlabelled by default). Pair the header with `Card`s, `StatusList`s or property rows for the record body — or an embedded routed island when the detail needs its own actions. ## The `info` slot The Redwood general overview is `main` + `info`: the overview, and a contextual side panel with secondary, read-only context — related contacts, recent activity, notes. Override `info(row, rq)`: ```java @Override protected Component info(Requisition r, HttpRequest rq) { return Card.builder().content(activityOf(r)).build(); } @Override protected GeneralOverviewDisplay display() { // optional return GeneralOverviewDisplay.defaults().toBuilder().promoteInfoSlot(Toggle.on).build(); } ``` On wide pages the panel sits beside the overview (`infoWidth()`, default `20rem`); below 48rem the two stack. **`promoteInfoSlot`** (the Redwood display option of the same name, default `off`) puts the info panel ABOVE the overview when they stack. `display().info()` = `off` drops the panel. Composed on the one responsive grid (a `ResponsiveGrid` template `"main info"`), so every renderer draws it. ![The info slot beside the overview](/images/docs/general-overview/info-slot.png) ### A switcher in the header of any page This archetype's switcher is a field in the page body. For a record or context switcher in the **page header** — on any page, not just this one, with type-ahead search and the `object`/`context` distinction — implement `RecordSwitcherSupplier`; see [Page templates › record switcher](/ux-patterns/page-templates/#record-and-context-switcher). ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Switcher + overview | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `info` slot | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `promoteInfoSlot` | ✅ | ✅ | ✅ | ✅ | 🟡 ¹ | ✅ | ✅ | ¹ Redwood places the info panel in its column; when the layout stacks it keeps the main-first order. ## Redwood parameter and slot reference What the Redwood `general-overview-page` template exposes, and what Mateu gives you for it. The canonical page-header elements shared by every template — title, avatar, status badge, `@KPI` facts, `@Timestamp`, peer navigation — are documented once in [Page templates](/ux-patterns/page-templates/); this table covers what is specific to this one. **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `selectContext` / `selectObject` `{data, itemText, secondaryText, avatar, icon}` | `switcherOptions(HttpRequest)` returning `Option`s | ✅ | | `selectContextValue` / `selectContextItem` (controlled selection) | the public `record` field, set by the switcher | ✅ | | `dataSwitcherType: context \| object` | the header switcher (`RecordSwitcherSupplier`, `RecordSwitcher.type`); this archetype's body switcher has no type | 🟡 | | `displayOptions.switcherSearch` (type-ahead inside the switcher) | the header switcher's `RecordSwitcher.searchable` | 🟡 | | `displayOptions.promoteInfoSlot` | `GeneralOverviewDisplay.promoteInfoSlot` | ✅ | | `displayOptions.contextualInfoLabel` / `contextualInfoSticky` | `@KPI` facts render, but neither toggle exists | 🟡 | | `displayOptions.density: standard \| compact` | `@Compact`, set on the view rather than as a template option | 🟡 | | `previousItem` / `nextItem` + `spPreviousItem` / `spNextItem` | `PeerNavigationSupplier` → `PeerNav` | ✅ | | **Slot** `main` | `overview(Row, HttpRequest)` | ✅ | | **Slot** `info` (contextual side panel) | `info(Row, HttpRequest)` + `infoWidth()` | ✅ | | **Slot** `search` | the app-level smart search bar / ⌘K palette, not a page slot | 🟡 | | **Slot** `announcement` (aria-live) | `UICommand.announce(text)` from any action | ✅ | | Switcher change event | `switchRecord` — re-renders in place, no navigation | ✅ | Mateu adds two things the Redwood template has no equivalent for: `emptyOverview()` (what shows before anything is selected) and `load(String id, HttpRequest)` as an explicit data port, so the switcher never carries the record payload. ## Demo `demo-admin-panel/.../generaloverview/RequisitionOverview.java` (`/general-overview-demo`). Tests: `GeneralOverviewSyncTest`. --- # Global entity search URL: https://mateu.io/ux-patterns/global-search/ > The ⌘K command palette searches your data — customers, bookings, invoices — not just the menu. **Status:** ✅ Implemented ## Intent Expert users navigate by **entity**, not by screen: "take me to *Acme's* file", not "Customers → search → Acme". The command palette already jumps to menu entries; wiring your data into it turns it into the app's front door. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Implement `GlobalSearchSupplier` on the `@UI` app class: ```java @UI("") public class BackofficeApp implements GlobalSearchSupplier { @Override public List<GlobalSearchResult> globalSearch(String searchText, HttpRequest httpRequest) { var hits = new ArrayList<GlobalSearchResult>(); customers.top(searchText, 5).forEach(c -> hits.add(new GlobalSearchResult(c.name(), c.taxId(), "/customers/" + c.id(), "Clientes"))); bookings.top(searchText, 5).forEach(b -> hits.add(new GlobalSearchResult(b.code(), b.guestName(), "/bookings/" + b.id(), "Bookings"))); return hits; } } ``` - While the user types in the **⌘K palette**, the menu results are joined (debounced) by the matching **entities**, grouped by `category`; arrow keys navigate across both; Enter (or click) navigates to the hit's `route`. - The palette calls the app-level `_globalsearch` action with the typed `searchText` — per request, so results can be permission-scoped (resolve the user from the request). - Keep it fast: search indexes, top-N per category. The palette shows at most 8 hits. ## Related - [Navigation & menus](/ux-patterns/navigation/) — the palette's menu half - [Filters & Listing](/ux-patterns/filters-and-listing/) — when the answer is a slice, not a record --- # Guided import URL: https://mateu.io/ux-patterns/guided-import/ > A wizard that turns a user's CSV into typed, validated records — upload, map columns, review problems, import. **Status:** ✅ Implemented ## Intent Let end users **load data in bulk from a spreadsheet** — a price list, an initial product catalogue, a batch of bookings — without asking IT to write a loader. The user brings a CSV that almost never matches your model exactly: different column names, a `;` separator, missing cells, `"quoted, values"`. A guided wizard absorbs those differences: it maps columns to fields, shows what will fail **before** anything is written, and imports only the clean rows. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `ImportWizard<Row>` and implement `importRows` — the wizard contributes the four steps: ```java @UI("/product-import") public class ProductImport extends ImportWizard<Product> { @Override protected void importRows(List<Product> rows, HttpRequest httpRequest) { rows.forEach(repository::save); } } ``` with a plain row class carrying the usual bean-validation annotations: ```java public class Product { @NotEmpty String name; int units; boolean active; } ``` The four steps: 1. **Upload** — a `@FileUpload(accept = ".csv")` field (the file is read client-side into a data URI, so no upload endpoint is involved) or a textarea to paste the CSV. Both `,` and `;` separators are detected automatically; quoted fields may embed separators, quotes and newlines. 2. **Mapping** — one grid row per CSV column showing a sample value from the first data row. The *target field* cell is an inline select over the row class's assignable fields, pre-filled by name similarity (exact case-insensitive match, then containment). Leave it blank to skip a column. 3. **Validation** — the report: valid/invalid row counts plus one issue line per problem, with the CSV line number, column, offending value and reason — conversion failures (`"abc"` into an `int`, a non-ISO date) and constraint violations (`@NotNull`, `@NotEmpty`, `@NotBlank`, `@Min`, `@Max`). This step carries the **Import** button. 4. **Result** — how many rows were imported and how many skipped. Only the valid rows reach `importRows`, already **typed** (`List<Product>`, coerced basics: strings, numbers, booleans, enums, ISO `LocalDate`/`LocalDateTime`/`LocalTime`). - `rowClass()` defaults to the `Row` generic argument; override it when generics can't tell. - Override `title()` for a custom heading (default: *Import Product*). - Everything is standard wizard machinery — the progress indicator, Back/Next, cross-step state — so `@WizardProgress(STEPS)` and the other wizard options apply. ## The `@FileUpload` field The upload step is built on a reusable piece: annotate any `String` field with `@FileUpload(accept = ".csv")` and it renders as a generic file picker (chosen file's name + Remove button, no preview — the generic sibling of `@UploadableImage`). The picked file travels in the field value as a **data URI**, with the original file name embedded as a `name=` data-URI parameter so it can be shown again and used as the download name; decode everything after the first comma as base64 on the server. ```java @FileUpload(accept = "application/pdf") String contract; ``` ## Principles served - **Workflow over screens** — a multi-step task (upload → map → verify → commit) modeled as one guided flow instead of a form dump. - **Recoverability** — nothing is written until the user has seen exactly which rows will fail and why; bad rows are skipped, never half-imported. ## Related - [Bulk actions](/ux-patterns/bulk-actions/) — operating on many existing records at once - [Inline CRUD editing](/ux-patterns/inline-crud-editing/) — the same in-place cell editors the mapping grid uses --- # Heatmap (calendar) URL: https://mateu.io/ux-patterns/heatmap/ > Show intensity over time — activity, usage, occupancy — GitHub-contributions style. **Status:** ✅ Implemented ## Intent Show *how much* happened *when* over a long stretch of days — commit activity, usage, occupancy, sales — as a calendar heatmap, so streaks, gaps and busy periods pop out at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Heatmap` component: one `HeatCell` per day with a `date` and a `value`. The renderer lays the days out in week-columns (Monday-first) and colors each square by intensity from 0 to the maximum value. `label` overrides the cell tooltip. ```java @Section("Commits this year") Component heatmap = Heatmap.builder() .cells(List.of( HeatCell.builder().date(LocalDate.of(2026, 3, 1)).value(2).build(), HeatCell.builder().date(LocalDate.of(2026, 3, 2)).value(5).label("5 commits").build() /* … one per day … */)) .build(); ``` ![Activity heatmap](/images/docs/heatmap/activity.png) The renderer is dependency-free (a CSS grid of squares), colors by four intensity buckets of the primary color, themes through the standard CSS variables, works in dark mode, scrolls horizontally when wide and shows a Less→More legend. On mobile (React Native) and the IntelliJ plugin the same values render as a compact grid. ## When to use it Use a `Heatmap` for **intensity across many days**. For a handful of dated events use a `Calendar`; for a trend line use a `TrendChart` or `Stat` sparkline. Demo: `/heatmap-demo`. --- # Hero search URL: https://mateu.io/ux-patterns/hero-search/ > A distraction-free landing page focused on searching one collection. **Status:** ✅ Implemented ## Intent Give users whose task starts with a search — find a hotel, a product, a candidate — a focused landing page: a big hero header, a prominent search box with filter facets, and results as cards. ## Problem Dropping users on a dense listing when their task is "search for X" buries the search box in toolbar chrome. Building a custom search landing by hand means rewiring search, facets, pagination and result rendering that Mateu's listing machinery already provides. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `HeroSearch<Filters, Row>` and implement `search(SearchRequest, HttpRequest)` exactly like any [listing](/java-user-manual/build/capability-listings/) (the archetype already declares `Searchable` and `Filterable<Filters>` for you). It renders a centered hero (title + subtitle, optional background image) followed by the standard searchable listing, with results as card tiles by default. ```java @UI("/hotel-search") @Title("Hotel search") public class HotelSearch extends HeroSearch<HotelFilters, Hotel> { public record HotelFilters(String zone, Integer minStars) {} public record Hotel(String name, String zone, int stars, String price) {} @Override protected String heroTitle() { return "Find your hotel"; } @Override protected String heroSubtitle() { return "Search by name or zone…"; } @Override public ListingData<Hotel> search(SearchRequest request, HttpRequest httpRequest) { // query your use case / repository with // request.searchText() + filters(request) + request.pageable() return ListingData.of(/* … the matching hotels */); } } ``` ![Hotel search](/images/docs/hero-search/hotel-search.png) - The `Filters` record fields become the **facets** of the search box (the standard [smart search bar](/ux-patterns/filters-and-listing/#the-smart-search-bar): they live in its *Filter by* panel and show as removable chips when applied). - Results render as **cards** by default — override `gridLayout()` to return `GridLayout.table` or any other layout. - The listing starts **empty** (distraction-free) and searches on enter. Add `@Trigger(type = TriggerType.OnLoad, actionId = "search")` on the class to preload results. - Override `heroImage()` to set a background image for the hero (a dark overlay keeps the text readable). ### Fluent variant `HeroSection` is a regular component: compose it with a fluent `Listing` (or anything else) from `ComponentTreeSupplier`: ```java HeroSection.builder() .title("Find your hotel").subtitle("…") .image("/images/hero.jpg").centered(true) .build() ``` ## Redwood parameter and slot reference What the Redwood `hero-search-page` template exposes, and what Mateu gives you for it. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `pageTitle` | `heroTitle()` | ✅ | | `description` | `heroSubtitle()` | ✅ | | Hero background | `heroImage()` (dark overlay keeps the text readable) — a Mateu addition, the Redwood hero has no image prop | ✅ | | `collectionView: on \| off` | the listing always renders; it just starts empty until the user searches | 🟡 | | `selection` | row clicks dispatch the listing's own actions | 🟡 | | `avatar` | `PageDto.avatar/icon` on the canonical header | ✅ | | `suggestions[]` (suggestion chips under the search box) + `spSuggestionAction` | — | — | | `descriptionHotspot {label, data}` + `spDescriptionHotspotAction` (clickable text inside the description) | — the subtitle is plain text | — | | **Slot** default (results) | the listing; cards by default, `gridLayout()` to change it | ✅ | | **Slot** `searchTemplate` | the standard smart search bar, with the `Filters` fields as facets | ✅ | | **Slot** `detailTemplate` | — pair it with [collection detail](/ux-patterns/collection-detail/) when you need an in-place detail pane | — | | **Slot** `announcement` (aria-live) | live regions are installed client-side for a11y, but the backend cannot declare announcement content | 🟡 | ## When to use it Use hero search when **searching is the task** and the page is an entry point (public catalogs, pickers, knowledge bases). Prefer a plain `AutoCrud`/`Listing` when the user works the collection (bulk edits, exports, dense scanning). --- # High-density screens URL: https://mateu.io/ux-patterns/high-density/ > Pack more information on a single page for operational workflows where every pixel counts. **Status:** ✅ Implemented — `@Compact` ## Intent Pack the maximum amount of relevant information on a single screen so operational users can work without scrolling or switching context. ## Problem Standard-density forms are designed for casual or occasional users: generous spacing, large controls, generous whitespace. That trade-off reverses for high-frequency operational screens — hotel check-in, call-centre detail views, trading dashboards, warehouse picking stations — where experienced users know the layout and pay the cost of scrolling or multiple tabs in every single action they take. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the page class with `@Compact`. ```java @UI("/checkin/:id") @Compact @Style(StyleConstants.FULL_WIDTH_WITH_PADDING) @Zones({ @Zone(name = "left", width = "64%"), @Zone(name = "right", width = "36%") }) public class CheckInForm { ... } ``` `@Compact` injects a Lumo CSS custom-property block onto the page container. Because Vaadin's design tokens cascade through shadow DOM, every component inside is automatically condensed: - Form layout inter-row gap reduced from ~`1em` to `0.2rem` - Control heights compressed (`--lumo-size-*` reduced by ~25 %) - Spacing tokens reduced proportionally - Field labels rendered at `xs` font size with tighter line height - Form-layout minimum column width reduced to `7em` (allows more columns at the same viewport width) - Grid/table rows rendered with Vaadin's built-in `compact` row theme Font size is intentionally left at the normal Lumo value so body text stays legible. ![High-density form — 4 columns with compact spacing](/images/docs/ux-patterns/high-density.png) ## Combining with other patterns `@Compact` pairs naturally with: | Technique | Why | |---|---| | `@Zones` | Two or three columns side by side maximise the use of horizontal space | | `@Style(StyleConstants.FULL_WIDTH_WITH_PADDING)` | Extend the form to the full viewport width instead of the default `900px` cap | | `@Tab` | Group secondary information into tabs so the primary data stays visible | | `@PlainText` on read-only fields | Eliminates input chrome (border, background) for display-only values | | `@ReadOnly` | Locks the form when the user is inspecting, not editing | ## Structure example ``` ┌────────────────────────────────────────────────────────────┐ │ Locator Hotel Agency Stay Board Balance │ ← header strip ├──────────────────────────────┬─────────────────────────────┤ │ Overview col×8 │ Amounts (grid) │ │ Waiting RateRef Type … │ │ ├──────────────────────────────┤ Room │ │ Check-in col×6 │ Room no Beds Status … │ │ Room no Type Upgrade … │ │ ├──────────────────────────────┤ Guest history │ │ Guests (grid) │ Loyalty Last hotel … │ ├──────────────────────────────┤ │ │ Customer col×8 │ Folios / Deposits │ │ [Profile] [Company] … │ Credit Card Balance … │ └──────────────────────────────┴─────────────────────────────┘ ``` ## Partial compact If only part of a page needs high density (e.g. a single section with a dense grid inside a normal-density page) apply `StyleConstants.COMPACT` directly via `@Style` on that field or element rather than the whole class: ```java @Style(StyleConstants.COMPACT) List<LineItem> lines; ``` ## Principles served - **Minimize navigation** — all relevant data visible in one screen, no scrolling or tab-switching - **Workflow over screens** — the screen is shaped around the operational task, not the data model - **Keyboard-first** — high-density users rely on tab order and keyboard shortcuts; `@Compact` does not affect focus or tab stops --- # Hover details URL: https://mateu.io/ux-patterns/hover-details/ > Read-only details that appear when pointing at something — a rate's night-by-night breakdown on a cell, a summary next to a link — with Popover (trigger hover) and @Tooltip. **Status:** ✅ Implemented ![A reservations listing; hovering a rate or guest shows its details](/images/docs/hover-details/reservations.png) ## Intent Back-office screens are dense: the rate of a reservation is one number in a column, but the clerk often needs *how* it was made — night by night, with the weekend supplement. Opening a page for that breaks the flow. The answer is a small panel that appears when pointing at the number (or focusing it from the keyboard) and goes away when the pointer leaves: OPERA Cloud's rate information and reservation summary popups. ## Solution ### On a listing cell: `@Tooltip("otherField")` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the row field whose cell should explain itself with the name of another field of the row; hovering the cell shows that field's text, keeping its line breaks: ```java public record ReservationRecord( String id, String guest, @Tooltip("rateBreakdown") BigDecimal rate, @HiddenInList String rateBreakdown) {} // "BAR · 6 nights\nThu 8 · 134 €\n…" ``` ### Anywhere: `Popover` with `trigger = hover` `Popover` wraps a component and shows its `content` next to it. By default it opens on **click**; with `PopoverTrigger.hover` it opens on **hover and on keyboard focus**, non-modal — for read-only details: ```java Popover.builder() .id("rateInfo") .trigger(PopoverTrigger.hover) .wrapped(new Text("rateInfoLink", "Rate information")) .content(VerticalLayout.builder().content(breakdownLines).build()) .build(); ``` Give each popover an `id` when a page has several. ## Where it works - **Vaadin** — `vaadin-popover` (`trigger` hover + focus; the click popover stays modal) and the grid's `vaadin-tooltip`. - **Redwood** — one shared JET `oj-popup` opened on hover/focus (or click) for both the popover and the cell; the popover's content is shown as text lines, and the wrapped component as its text. Inside an `oj-table` the cell detail opens on hover (the table moves keyboard focus between cells, not into them). - **IntelliJ plugin** — a floating panel (hover/focus, Esc closes) and the table's tooltip. - **React Native** — no hover on a touch screen: a popover opens on press, a cell's detail on long-press. - .NET: `Popover { Trigger = PopoverTrigger.Hover }`, `[Tooltip("rateBreakdown")]`; Python: `Popover(trigger=PopoverTrigger.hover)`, `Annotated[..., Tooltip("rate_breakdown")]`. Demo: `demo-vb-pms` — the Reservations listing's rate column and the reservation page's "Rate information". --- # How Mateu's UX is evaluated URL: https://mateu.io/ux-patterns/how-ux-is-evaluated/ > The method behind Mateu's UX quality bar — heuristic reviews, task walkthroughs, synthetic users, task metrics and accessibility probes on every renderer — what it catches and what it cannot. **Status:** ✅ Method defined and run on the web renderers (October 2026, see [Results](#results)); the native renderers are reviewed separately. ## Intent Mateu generates the screens, so the screens' usability is Mateu's responsibility, not the app developer's. The aim for the supported renderers is that what Mateu generates is **correct** — and optimal where possible — and **pleasant to look at**, without a brand identity of its own: each renderer stays inside its design system (Lumo for Vaadin, Redwood tokens for the VB renderer), so a Mateu app looks like a well-made app of that design system. This page says how that is checked, so the bar is explicit and repeatable — every UX claim in these docs should be traceable to one of the methods below. ## Without user testing — on purpose, and what that costs The evaluation does **not** rely on sessions with real users. It uses inspection and simulation methods instead, several of them, so that what one misses another tends to catch. Be clear about the limit: no inspection method fully replaces watching real people. What it catches less well is **domain misunderstanding** (a label that is precise to us and ambiguous to a hotel receptionist) and **unwritten expectations** (what a user assumes a screen will do from the tools they already use). If your organisation can run user tests on its own Mateu apps, do — and report what you find; it improves the generator for everyone. ## The methods ### 1. Heuristic evaluation (two passes) Every pattern and component, on every supported renderer, in light and dark, desktop and mobile widths, reviewed against: - **Nielsen's 10 usability heuristics** (and the NN/g guidance on forms, tables, error messages, empty states and dashboards) — the checklist; - **visual craft** criteria from *Refactoring UI* (Wathan & Schoger): hierarchy, spacing on a fixed scale, consistent size progression, colour used for meaning, restraint. Each finding cites the heuristic or principle it violates. ### 2. Cognitive walkthroughs per task For each typical task — create a record, find one and edit it, filter and export, complete a wizard, recover from a validation error, find a screen through the menu, undo a mistake — each step is checked with four questions: 1. Will the user know what to do at this point? 2. Will they see the control that does it? 3. Will they connect the control with what they want? 4. After acting, will they understand the response? A "no" anywhere is a finding. ### 3. Synthetic users Agents use the demo apps in a **real browser**, knowing only the goal of the task — not the code, not the docs. They log where they hesitate, what they looked for and did not find, wrong turns, and how many steps and errors the task cost. Run with several profiles: - a first-time user; - a keyboard-only expert; - a phone-width user; - a screen-reader user (navigating by the accessibility tree only). This is a simulation, not a substitute for people; its value is breadth and repeatability — the same tasks can be re-run after every change. ### 4. Task metrics The walkthrough tasks are also scripted with Playwright and **measured**: clicks, steps, time to completion, recoverable errors. Every fix is measured before and after, so an improvement is a number, not an opinion. ### 5. Accessibility - **axe-core** on every screen of the demo and test apps; - the **behaviour probes** that axe cannot replace (focus management in overlays, keyboard operation, live-region announcements, focus after navigation and after a rejected save) — see [Accessibility](/ux-patterns/accessibility/) — on the web renderers, Redwood, React Native and IntelliJ; - **200 % zoom** and **forced-colours / high-contrast** modes; - conformance target **WCAG 2.2 AA**, with WAI-ARIA Authoring Practices for widget behaviour. ### 6. The developer journey The developer is a user too. From the documentation alone: new project in the IDE → first screen → first CRUD → deploy. Every place where the docs, the IDE tooling or an error message leaves the developer stuck is a finding. ### 7. Pattern comparison Mateu's patterns are compared with the enterprise design systems that document theirs — IBM Carbon, SAP Fiori, Microsoft Fluent 2, Material 3, Atlassian and Oracle Redwood — and with the pattern literature (Tidwell's *Designing Interfaces*, Cooper's *About Face*; Silver's *Form Design Patterns* and Wroblewski for forms; Few for dashboards). **Patterns, not style**: the question is whether the interaction is right, never whether it looks like someone else's product. ## Visual consistency rules Some of the bar is mechanical, so it is enforced by tests rather than reviews: - spacing, type, colour, radius and elevation come from the **design system's tokens**; a guard test fails on hard-coded values in Mateu's own components; - one icon family per renderer (no mixing a design-system icon set with emoji); - consistent size progression for buttons and controls (S / M / L); - dashboards: every chart names its metric and has a legend whose colours match; every number states its timeframe; one date format per locale; tables sorted meaningfully by default. ## How findings are handled Each finding records: the screen and renderer, steps to reproduce, a screenshot, the method that found it, the reference it cites, and a priority: | Priority | Meaning | |---|---| | **P1** | blocks or misleads the user, or fails WCAG AA | | **P2** | slows the user down or causes recoverable errors | | **P3** | polish: inconsistency, visual noise, sub-optimal default | P1 and P2 are fixed in the generator before the release they are found in; P3 are fixed or recorded with a reason. Because the screens are generated, a fix applies to **every Mateu app** at once. ## Results ### Web renderers (Vaadin and Redwood/VB) — pre-beta review, October 2026 The first full run of the method covered **145 screens** of four apps (the e2e SUT, the admin demo, the VB demo and the PMS demo) in light and dark at desktop and phone width — 580 screenshots, each checked with axe —, seven tasks walked by four synthetic users (mouse, phone, keyboard-only and screen-reader), 200 % zoom and forced colours. Every finding, with its screen, method, reference and priority, is in [`design/ux-review/web-findings.md`](https://github.com/miguelperezcolom/mateu/blob/master/design/ux-review/web-findings.md). What changed in the generator, so in every Mateu app: - **Forms reflow on a phone.** Two-column forms used to keep both columns at 390 px and cut the second one off; they now collapse to one column, and a page without an app shell keeps a side gutter. - **Wizards finish.** A completion action that answers with a message now lands on the result step (it left the last step open for editing under the toast). - **Destructive actions are guarded and explicit.** A selection-dependent action (Delete) is disabled until rows are selected instead of answering with an error; its confirmation is a real modal dialog that takes the focus and says what will happen ("Delete the selected items? — Cancel / Delete"). - **Accessible names and contrast.** Boolean cells, progress bars, in-cell editors, lookups, icon buttons and hidden-label fields are named; informative text no longer uses placeholder grey; text on data-supplied colours picks a readable ink. (Redwood has since become light only.) - **Tables read like tables.** Numeric columns are right-aligned and grouped in the page locale; booleans read Yes/No; status constants read as words; the search box finds what the listing shows; a search-first page invites a search instead of shimmering and then saying "Nothing here yet." - **One icon family per renderer.** Notices, the command center, file lists and the other components that drew emoji or their own SVGs now use the design system's icon set. - **A guard against regressions.** `scripts/check-design-tokens.mjs` runs in CI and fails when a hard-coded colour, spacing or font size is added to Mateu's own components outside the design tokens (a ratchet over today's count). Task completion by the synthetic users went from **13/28 to 24/28** runs, and axe violations across the 580 screens fell from **1 193 to 136** (−89 %). All 15 P1 findings were fixed. What is still open — whole-row click on listings, dashboard timeframes, a few Redwood dark-mode surfaces — is listed in the findings file with the reason it is open. --- # Idle-session warning URL: https://mateu.io/ux-patterns/idle-session/ > After a period without activity in any tab, a modal counts down before signing out; "Stay signed in" keeps the session, "Sign out" goes to the app's logout. **Status:** ✅ Implemented · `@Experimental` ![The idle warning counting down, focus on "Stay signed in"](/images/docs/idle-session/warning.png) ## Intent Shared terminals — a front desk, a counter, a ward — must not stay signed in for whoever walks up next. Security policies ask for a sign-out after a period of inactivity, and users ask not to lose their work to it without warning. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @App(idleTimeoutMinutes = 15, idleWarningSeconds = 60, idleSignOutUrl = "/logout") public class Shell implements KeepAliveHandler { @Override public void keepAlive(HttpRequest httpRequest) { // optional: refresh whatever "signed in" means for this app (a token, a session) } } ``` After `idleTimeoutMinutes` minus `idleWarningSeconds` without activity, a modal says **"Are you still there?"** and counts down: - **Stay signed in** (also **Esc**, and the button that has the focus) runs the app-level `_keep-alive` action — reaching the server is what renews an ordinary server session; a `KeepAliveHandler` on the app class is called too. - **Sign out**, or the countdown reaching zero, goes to `idleSignOutUrl` with a full page load — typically the app's logout endpoint. Blank: the app's own route. Mateu does no authentication: what "signed in" and "sign out" mean is the app's. Before navigating, a cancelable `mateu-idle-sign-out` event is dispatched on `document` (detail `{ url }`) — an app with its own sign-out (an OIDC library, say) calls `preventDefault()` and does it itself. ### Every tab counts Activity is **shared by the tabs** of the app: each tab records its last key press, click, wheel or touch (not scroll: a shell scrolls by itself) in `localStorage` (at most every 5 s), and each tab measures idleness from the latest activity of **any** tab. Working in one tab keeps the others from warning; **Stay signed in** in one tab dismisses the warning in all; **Sign out** in one signs out the others. While the warning is up only *Stay signed in* keeps the session — a stray mouse move must not cancel a warning nobody saw. ### In YAML ```yaml type: AppShell idleTimeoutMinutes: 15 idleWarningSeconds: 60 idleSignOutUrl: /logout ``` ## How it relates to session expiry The two cover different ends: | | Idle warning | [Session expiry](/ux-patterns/session-expiry/) | |---|---|---| | Who decides | the **client**, from the user's inactivity | the **server**, which answers 401 | | When | before anything expires | after the token or session expired | | What happens | a countdown; stay or sign out | the request is held; the app re-authenticates and it is retried | They compose: if the server session has already expired when the user presses *Stay signed in*, the keep-alive request gets a 401 and goes through the session-expiry handling like any other request. Set the idle timeout **shorter** than the server's session so the warning comes first. ## Accessibility The warning is a modal `alertdialog`, labelled and described; the focus moves to **Stay signed in** (so Enter never signs out) and is trapped; Esc stays. The remaining time is announced again at 10 seconds. ## Where it works - **Vaadin** — the shared `mateu-idle-warning` element. - **Redwood (Oracle VB)** — an `oj-dialog` with the same cross-tab rules. - **React Native** — every touch counts; time in the background counts as idle; a modal with the countdown. - **IntelliJ plugin** — IDE activity counts; a modal countdown dialog. - Also from the C# (`[App(IdleTimeoutMinutes = 15)]`, `IKeepAliveHandler`) and Python (`@app(idle_timeout_minutes=15)`, `KeepAliveHandler`) backends. Demo: `demo-admin-panel` → `/e2-demo` (one minute, a 30-second countdown). ## Related - [Session expiry](/ux-patterns/session-expiry/) - [Autosave](/ux-patterns/autosave/) — shrink the work an expiry can cost --- # Inline editing in listings URL: https://mateu.io/ux-patterns/inline-crud-editing/ > Edit CRUD rows directly in the listing grid; each cell commit persists its row. **Status:** ✅ Implemented — class-level `@InlineEditing` ## Intent Let users fix values in a collection — stock counts, prices, flags — right where they see them: in the listing grid, without opening the detail form. ## Problem The default CRUD flow persists through the detail form: click the row, edit one field, save, go back. For quick tabular corrections across many rows that round-trip dominates the task. [Editable table](/ux-patterns/editable-table) solves this for **form collections** (`@InlineEditing` on a `List` field); listings backed by a repository needed the same directness. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the `AutoCrud` class itself with `@InlineEditing`. Every data column becomes an editable input in place (a field marked `@ReadOnly` stays display-only), and **each committed cell persists its row immediately** through `CrudStore.save(...)` — no explicit save button. ```java @UI("/stock") @Title("Stock (edit in place)") @InlineEditing public class StockCrud extends AutoCrud<StockItem> { @Override public GridLayout gridLayout() { return GridLayout.table; } // cell editing lives in the table layout @Override public CrudStore<StockItem> store() { /* … */ } } ``` ![Stock listing with in-place editors](/images/docs/inline-crud/stock-crud.png) The editor per column is derived from the field's real Java type — the same mapping as [editable tables](/ux-patterns/editable-table): text, integer/number, checkbox, enum combo, date/time pickers. Under the hood each commit dispatches the crud's `update-row` action with the edited row; `AutoCrud` loads the stored record the row names, lays the row over it and calls `store().save(entity)`. It is guarded like the editor's save: a `@ReadOnly` (or otherwise not writable) field keeps the stored value whatever the request carries, the record's other fields survive (a row carries only its columns), an id with no stored record is refused — never inserted —, and the action exists only on a crud annotated `@InlineEditing` whose `canEdit()` is true (any other crud answers a crafted `update-row` with 403). Override `updateRow(Map, HttpRequest)` to customise persistence (auditing, a database-side partial update) — and keep those guarantees. The .NET (`[InlineEditing]`) and Python (`@inline_editing`) ports behave the same. ## When to use it Use it for **flat, operational collections** where values change often and rows are simple. Keep the default detail-form flow when rows have nested data, cross-field validation, or when edits must be reviewed before persisting. --- # Item overview URL: https://mateu.io/ux-patterns/item-overview/ > Keep an item's key information pinned while exploring the rest in tabs. **Status:** ✅ Implemented ## Intent Keep the key information about the item the user is working on — name, status, stock, price — always visible in a left-hand panel, while the rest of the page (charts, specifications, history) is organised in tabs. ## Problem On tabbed detail pages the identifying information lives in the first tab, so as soon as the user switches to "Reviews" they lose sight of what item they are looking at. Repeating the header in every tab wastes space and drifts out of sync. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `ItemOverview`. The first component field is the **key-info panel** (left, sticky — it stays put while the right side scrolls); each component field annotated with `@Panel` becomes a **tab**. ```java @UI("/product/:id") @Title("Ergonomic chair EC-200") public class ProductOverview extends ItemOverview { Markdown keyInfo = new Markdown(""" ### Ergonomic chair EC-200 **SKU:** EC-200-BLK · **Stock:** 143 · **Price:** 349 € """, null, null); @Panel(title = "Sales") Chart sales = Chart.builder().chartType(ChartType.bar) /* … */ .build(); @Panel(title = "Specifications") Markdown specs = new Markdown("| Property | Value | …", null, null); @Panel(title = "Reviews") Markdown reviews = new Markdown("⭐⭐⭐⭐⭐ …", null, null); } ``` ![Product overview](/images/docs/item-overview/product-overview.png) Override `panelWidth()` (default `22rem`) to size the key-info panel. As a routed page, an item overview has a page toolbar like any other page: its `@Toolbar` (and `@Button`) methods and fields show there and run on it. Routed at a CRUD's `:id` (an authored route), it also gets that CRUD's **Back to list** and **Edit** — see [CRUD navigation flow](/java-user-manual/build/crud-navigation-flow/#the-cruds-navigation-on-your-page). An item overview can also be the content of a CRUD's record page, under the CRUD's own header and toolbar: the record class implements `DetailContentSupplier` and returns it — see [The record page](/java-user-manual/build/customizing-crud-and-listings/#the-record-page). ## Redwood parameter and slot reference What the Redwood `item-overview-page` template and its `item-overview` key-info pattern expose, and what Mateu gives you for them. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope ### Page (`item-overview-page`) | Redwood prop / slot | Mateu | | |---|---|---| | **Slot** `overview` (key info) | the first component field, sticky; width via `panelWidth()` (default `22rem`) | ✅ | | **Slot** `main` | component fields annotated `@Panel`, rendered as tabs | ✅ | | `overviewExpanded` + `spOverviewCollapse` | — the key-info panel is always expanded | — | | `nextItem` / `previousItem` + `getPreviousNextItems` | `PeerNavigationSupplier` → `PeerNav` | ✅ | ### Key-info pattern (`item-overview`) | Redwood prop / slot | Mateu | | |---|---|---| | `itemTitle` / `itemSubtitle` | compose them in the key-info panel — typically an `EntityHeader`, which the renderer hoists into the page header | ✅ | | `photo {src}` | `EntityHeader` image / any component in the panel | ✅ | | `badge {text, style: strong \| subtle, position: leading \| trailing}` | `@BadgeInHeader` / `EntityHeader` badges; no `position` control | 🟡 | | `isFavorite` + `spExpand` | — | — | | `displayOptions {edit, share, favorite}` | — no built-in affordance bar; declare your own buttons | — | | **Slots** `body` / `footer` | the panel is a single component tree; compose a `VerticalLayout` | 🟡 | | `spEdit` / `spShare` | your own `@Action` methods behind declared buttons | 🟡 | ## When to use it Use item overview for **read-mostly detail pages** where identity context matters across categories. If the user must *edit* the item, prefer `AutoEditableView`; if the categories must be visible simultaneously rather than tabbed, use the [Foldout](/ux-patterns/foldout) pattern; for a long single-flow page with an index, use `@Toc` + sticky sections. --- # Kanban board URL: https://mateu.io/ux-patterns/kanban/ > Show work organized in columns of cards — a backlog, a pipeline, a sprint. **Status:** ✅ Implemented ## Intent Show items grouped by stage — a task pipeline, a sales funnel, an approval flow — as columns of cards, so the shape of the work (what's stuck, what's in flight, how much is done) reads at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Kanban` component: one `KanbanColumn` per stage, each holding `KanbanCard`s. A card carries a title, an optional description, a small `badge` (a tag or estimate) and an optional accent `color`. Give a card an `actionId` to make it clickable — a click dispatches the standard `action-requested` event, so an `@Action` method with that name runs (drill-in). ```java @Section("Sprint 24") Component board = Kanban.builder() .columns(List.of( KanbanColumn.builder().title("In progress").color("#3b82f6") .cards(List.of( KanbanCard.builder().title("Kanban component") .description("Ship the new board widget") .badge("8 pts").color("#3b82f6") .actionId("openCard").build())) .build(), KanbanColumn.builder().title("Done").color("#10b981") .cards(List.of( KanbanCard.builder().title("Chat file upload") .badge("13 pts").color("#10b981").build())) .build())) .build(); ``` ![Sprint board](/images/docs/kanban/sprint-board.png) The renderer is dependency-free (plain CSS flexbox), themes through the standard CSS variables, and works in dark mode. Columns scroll horizontally when they overflow; each column header shows its card count; the card's `color` tints its left border. ## When to use it Use a Kanban to **visualize** work by stage. It is read-only by design in this version (no drag-and-drop) — for moving cards between stages, make each card `actionId`-clickable and open a form/dialog that changes the item's stage, then re-render. Demo: `/kanban-demo`. --- # Keyboard Shortcuts URL: https://mateu.io/ux-patterns/keyboard-shortcuts/ > First-class keyboard navigation for power users. **Status:** ✅ Implemented — `@Action(shortcut = ...)`, `@Tab(shortcut = ...)` ## Intent Let expert users complete frequent tasks without touching the mouse. ## Problem Users who spend hours in a backoffice application are slowed down every time they must reach for the mouse to trigger a common action. A keyboard-hostile interface is the *Desktop Denial* anti-pattern: it penalises the users who know the system best. ## Solution ### Action shortcuts — `@Action(shortcut = ...)` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Attach a keyboard shortcut to any action. The shortcut is active whenever the view that owns the action is focused. ```java @Action(shortcut = "ctrl+s") public void save() { orderService.save(this); } @Action(shortcut = "ctrl+enter") public void submit() { workflowService.submit(this); } @Action(shortcut = "escape") public void cancel() { } ``` Shortcut strings follow standard modifier notation: `ctrl`, `shift`, `alt`, `meta` (⌘ on Mac), combined with a key name (`s`, `enter`, `escape`, `f2`, etc.). ### Enter key To run an action when the user presses Enter, give it `@Action(shortcut = "enter")`. (There is no `OnEnter` trigger type.) Listings search on Enter by default (`searchOnEnter`). ### Tab shortcuts — `@Tab(shortcut = ...)` Attach a shortcut to a tab so users can jump straight to it without the mouse. Use the same modifier notation as action shortcuts. ```java @UI("/order") public class OrderForm { @Tab(value = "Customer", shortcut = "alt+1") String customer; @Tab(value = "Items", shortcut = "alt+2") String items; @Tab(value = "Billing", shortcut = "alt+3") String billing; } ``` Pressing the shortcut selects the matching tab in place — no server round-trip, no navigation. `alt+<number>` reads naturally as "go to tab N" and avoids clashing with text input. :::tip[One tab strip per form] Tabs are grouped by consecutive fields that share the same `@Tab` name. Avoid putting a `@Section` on each tab's fields if you want a single tab strip — a section boundary per tab splits the form into several separate one-tab strips. ::: ### Default open tab — `@Tab(open = true)` By default the first declared tab is selected when the strip first renders. Mark a different tab with `open = true` to have it be the one shown initially instead: ```java @Tab(value = "Customer", shortcut = "alt+1") String customer; @Tab(value = "Items", shortcut = "alt+2", open = true) // ← selected on first render String items; @Tab(value = "Billing", shortcut = "alt+3") String billing; ``` `open` is independent of `shortcut`: the shortcut selects the tab on demand, `open` only sets the initial selection. If several tabs in the same strip declare `open = true`, the first one wins. Useful when the most relevant tab isn't the first — e.g. a detail drawer whose most-used section should be front and center as soon as it opens. ### Section index shortcuts — `@Toc` On a long page with a [sticky sections index](/ux-patterns/sections-index/), `Ctrl+Alt+1..9` jump to the first nine sections (same as clicking the index entry). This is on by default whenever the index is shown — no extra configuration. The shortcut number is shown as a faint badge on each index entry. ### Grid row selection — `@OnRowSelected(shortcut = ...)` Give a grid's row-selection action a `shortcut` base so users can select a row by position: the base combo plus a digit selects that row. ```java @Stereotype(FieldStereotype.grid) @OnRowSelected(value = "onGuestSelected", shortcut = "ctrl+shift") List<GuestData> guests; ``` `Ctrl+Shift+1` selects the first row … up to the ninth, exactly as if the row had been clicked (it fires the same `@OnRowSelected` method, so any master/detail wiring reacts identically). ### Keyboard-layout independence Shortcuts are matched by physical key (`e.code`) as well as logical key, so `Ctrl+Alt+<letter>` and `<modifier>+<digit>` work regardless of the keyboard layout — even where e.g. a Spanish layout's AltGr remaps `Ctrl+Alt+E` to `€` — and the numeric keypad works too. Buttons that carry a shortcut show it in their tooltip. ## App-wide shortcuts Shortcuts that belong to the APP rather than to one screen — **F9 for reservations everywhere**, quick-launch codes typed in the command palette, a **?** list of every key — are declared with `@AppShortcut` on the app class. A screen's own shortcut wins on the same key. See [App-wide shortcuts and quick launch](/ux-patterns/app-shortcuts/). ## Recommended shortcuts Consistent conventions across the application reinforce the *Consistency* principle. | Action | Suggested shortcut | |---|---| | Save / Submit | `Ctrl+S` | | Confirm / Send | `Ctrl+Enter` | | Cancel / Close | `Escape` | | New record | `Ctrl+N` | | Delete | `Ctrl+Delete` | | Search / Filter | `Enter` (via `@Trigger`) | ## Access keys mode (`@App(accessKeys = true)`) Back-office suites let the user **hold a key to see the keys** (OPERA Cloud with its access key): annotate the app class with `@App(accessKeys = true)` and holding **Alt** shows a small badge next to every visible button and tab — - the **declared shortcut** when the button's `@Action(shortcut)` (or a `@Tab(shortcut)`) has one; - otherwise a **letter of its label**, assigned automatically without repeats (word initials first, then any letter, then digits; letters taken by `alt+<letter>` shortcuts are skipped). **Alt + that letter** presses it; letting go of Alt hides the badges. The letter is matched by physical key, so it works on macOS (where Alt changes the character) and any keyboard layout. ```java @App(value = AppVariant.HAMBURGER_SECTIONS, accessKeys = true) public class PmsHome { … } ``` Works on Vaadin and Redwood; the IntelliJ plugin maps it to Swing **mnemonics** (its native access keys); React Native has no hardware-key model, so the flag is ignored there. .NET: `[App(AccessKeys = true)]`; Python: `@app(access_keys=True)`. On **Redwood**, `@Action(shortcut)` (combinations with Ctrl, Alt or Meta) and `@Tab(shortcut)` work the same as on Vaadin. ## Principles served - **Keyboard-first** — frequent tasks require no mouse gesture - **Consistency** — the same shortcut does the same thing everywhere in the app - **Workflow over screens** — shortcuts let users stay in flow without stopping to navigate --- # Layout inference URL: https://mateu.io/ux-patterns/layout-inference/ > Declare only the information — annotate a class with @AutoLayout and Mateu picks the right UX pattern from the amount and structure of the declared data. **Status:** ✅ Implemented ## Intent Let the developer declare **only the information** — which fields exist, which are required, how they are grouped — and let Mateu decide **how to present it**: fold the optional fields away, turn a long read-only page into tabs, render a small enum as radio buttons. The class stays a plain data declaration; the UX pattern is inferred. ## Problem Choosing the right presentation for a form is repetitive design work: a long editable form should not bury its required fields under twenty optional ones; a heavy read-only record reads better with random access than as an endless scroll; a three-value enum deserves radio buttons, not a dropdown hiding its options. Developers either hand-tune every screen with layout annotations or ship the default flat form and let usability suffer. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the class with `@AutoLayout`: ```java @UI("/customers/new") @AutoLayout public class NewCustomerForm { public enum Segment { RETAIL, BUSINESS, ENTERPRISE } @NotNull String name; @NotEmpty String email; @NotNull String phone; @NotNull Segment segment = Segment.RETAIL; @Stereotype(FieldStereotype.textarea) String deliveryNotes; @Stereotype(FieldStereotype.textarea) String billingNotes; @Stereotype(FieldStereotype.textarea) String internalNotes; @Stereotype(FieldStereotype.textarea) String marketingPreferences; String website; String vatNumber; } ``` Nothing in this class says "accordion", "tabs" or "radio" — yet the rendered form keeps the four required fields visible, collapses the six optional ones into a **More options** panel, and renders `segment` as radio buttons. Inference is **deterministic**: every decision is based on the declared structure — number of sections, estimated visual weight of the fields, required vs optional — never on runtime data. The same class always renders the same way. Determinism is not the same as **stability under model evolution**, though: the rules are threshold-based, so adding or removing a field *can* flip the inferred layout when the class crosses a threshold (that is the point of inference — the presentation follows the information). To make that visible instead of surprising, Mateu logs a **one-time warning** when a class under `@AutoLayout` sits within 2 weight units (or one section) of a threshold: ```text WARN @AutoLayout stability: com.acme.NewCustomerForm is close to the 'fold-optionals' threshold: weight 15 is within 2 units of the threshold (16) — adding or removing a field may flip the inferred layout. Pin the layout with explicit annotations (@Section, @Tab, @FoldedLayout…) if it must not change as the model evolves. ``` If a screen's layout must not change as the model evolves, pin it with explicit annotations — explicit always wins, so inference steps aside. ### The weight unit Rules are measured in *standard field-row units* (1 = one regular input), so thresholds hold across very different field mixes: a textarea, rich-text, HTML, markdown or image field counts as **4**, a grid or nested component as **6**, radio/checkbox as **2**, and anything else as **1**. ### Rule 1 — fold optionals into "More options" On an **editable** form where you declared no grouping at all (no sections, no tabs) and the estimated weight exceeds one screen (> 16 units), the required fields stay visible and the optional fields are collapsed into a **More options** accordion panel. The rule needs at least one required and at least four optional fields to be worth applying, and it never fires when the form contains tabs, `@Inline` subforms or embedded components — their layout is not Mateu's to rearrange. ![Editable form with optionals folded into a More options panel](/images/docs/layout-inference/fold-more-options.png) Folding **regroups, never drops**: every field still reaches the browser and round-trips normally. ### Rule 2 — read-only sections become adaptable tabs A long **read-only** view (the render context is read-only, or the class is `@ReadOnly`) with many substantial sections — at least 5 sections totalling ≥ 30 weight units — reads better with random access than as a long vertical stack, so the sections are presented as **tabs**, one per section: ```java @UI("/customers/360") @AutoLayout @ReadOnly public class Customer360 { @Section("Profile") @Stereotype(FieldStereotype.textarea) String summary; @Stereotype(FieldStereotype.textarea) String address; @Section("Billing") @Stereotype(FieldStereotype.textarea) String billingTerms; // ... Shipping, Activity, Notes ... } ``` ![Read-only sections presented as tabs](/images/docs/layout-inference/sections-as-tabs.png) The rule applies to read-only views only: on an **editable** form, hiding groups behind tabs could hide an invalid required field from the user, so editable sections always stay stacked. ### Rule 3 — small enums as radio buttons An enum field with up to **4 constants** renders as radio buttons instead of a dropdown: every option is exposed at a glance for the cost of one extra row. Beyond 4 constants the dropdown stays, as it is denser. To force radio buttons regardless of the enum size — with or without `@AutoLayout` — annotate the field with `@UseRadioButtons` (equivalent to `@Stereotype(FieldStereotype.radio)`, but self-documenting). ## Page-level inference: `@AutoPage` The same idea, one altitude up: `@AutoLayout` infers the presentation of a *form*; `@AutoPage` infers the page **archetype** from the declared information. Page inference is **on by default**: a plain view whose shape spells an archetype composes it automatically — you don't need to annotate anything. The template is the *default inferred output*; you keep declaring data and override when you want to. `@AutoPage(false)` opts a class out (keeping the plain-form rendering), and a global switch disables it everywhere. The explicit `@AutoPage` below is therefore optional — it's shown for clarity. ```java @UI("/ops") public class Ops { MetricCard revenue = MetricCard.builder().title("Revenue").value("1.2").unit("M€").build(); MetricCard occupancy = MetricCard.builder().title("Occupancy").value("87%").build(); @Panel(title = "Monthly sales") Text sales = new Text("Sales are up 12% on last month."); } ``` Nothing in this class extends `Dashboard` — yet it renders as one: the consecutive `MetricCard` fields group into the KPI scoreboard band, the `@Panel` field becomes a titled tile on the grid, and the page is typed `dashboard` on the wire. Actions keep routing to your class. ![A plain @AutoPage class rendered as a dashboard](/images/docs/layout-inference/auto-page-dashboard.png) Demo: `/auto-dashboard-demo` in `demo-admin-panel` (`InferredOpsDashboard`) — compare with `/dashboard-demo` (`SalesDashboard`), which declares the same intent by subclassing. The same applies to landings: a class declaring **only** `Button` fields and `@Panel` tiles — no data fields — composes the `Welcome` archetype: buttons become hero calls-to-action (the hero title comes from `@Title`) and panels become highlight tiles. A single data field keeps the class a form: a page made only of calls-to-action is a landing; a form that happens to have a button is not. Rules are deliberately few and only cover archetypes that are **fully derivable** from the declared fields (today: the dashboard and welcome rules). Shapes that resemble an archetype but would need information you didn't declare — like `CollectionDetail`'s id/title functions — are not composed; instead Mateu logs a one-time hint naming the archetype so you can adopt it explicitly. Explicit always wins: archetype subclasses, listing backends and fluent component trees are never rewritten, `@AutoPage(false)` opts a class out (and `mateu.page.inference.enabled=false` turns it off globally — see [Global switches](#global-switches)), and extending the archetype remains the way to take fine control (e.g. `columns()`). ### `@Aside` — a content-page from a plain form The minimal way to get the Redwood content-page grammar without composing anything: on an ordinary form, mark one component-holder field `@Aside`. That field is pulled out of the form body and placed in the contextual **aside**; the rest of the form becomes the **main** region of a `ContentLayout` (the aside sits beside main on wide viewports and stacks under it when narrow; `position`/`width`/ `sticky` come from the annotation). You keep declaring data as usual and just point at the one supporting panel that belongs to the side. ```java @UI("/profile") public class Profile { String name; String email; @Aside(width = "20rem") Markdown help = new Markdown("Need help? Contact support.", null, null); } ``` `@AutoPage` and `@Aside` have full backend parity: `[AutoPage]`/`[Aside]` in C# and `@auto_page`/`Aside()` in Python apply the same rules and emit the same wire. ### Guarding against flips in CI Inference means a model change can legitimately flip a page's template. To make that a reviewed decision instead of a surprise, pin your screens' fingerprints in a golden test: ```java assertThat(PageFingerprint.of(Ops.class)) .isEqualTo("pageType=dashboard composes=dashboard"); ``` `PageFingerprint.of(...)` captures the page-level decisions (`pageType` + composed archetype); when a change flips one, the test fails with a readable diff. The runtime [threshold-proximity warning](#staying-in-control) covers the form-level rules the same way. ## Staying in control Inference only fills the gaps you left open — it never overrides a decision you made: - **Explicit annotations always win.** `@Section`, `@Tab`, `@Zones`, `@FoldedLayout`, `@Toc`, `@Stereotype`, `@UseRadioButtons`… are respected as declared; inference works around them or steps aside. - **The tabs rule has explicit opt-outs**: a `@Section(sticky = true)` section or a class-level `@Toc` means you chose the pinned/scroll layout, so sections are never turned into tabs; `@Zones` and `@FoldedLayout` layouts are likewise untouched. - **Per-class opt-out**: `@AutoLayout(false)` disables inference for one class when it is enabled globally. - **Global opt-in**: set `mateu.layout.inference.enabled=true` to enable inference for every class without annotating each one — then use `@AutoLayout(false)` on the exceptions (see [Global switches](#global-switches)). - **Composable**: `@AutoLayout` targets `ANNOTATION_TYPE` too, so it can be bundled into your own [semantic annotations](/java-ui-definition/annotations/semantic-annotations/) (e.g. a company-wide `@StandardForm`). ## Renderer adaptation: `groupRelationship` and `adaptable` Inference does not just pick a widget — it tells the renderer **what the grouping means**, so each renderer (web, desktop, mobile) can adapt it to its medium. The tab layout on the wire carries two semantic hints: - `groupRelationship` — the semantic relation between the groups: `alternative` (the user looks at one group at a time — what tabs express), `sequential` (steps), or `simultaneous` (side by side). Developer-declared tabs and inferred section-tabs both emit `alternative`. - `adaptable` — `true` when the class is under `@AutoLayout`: the developer delegated the presentation, so a renderer **may degrade the tabs to an accordion** on a narrow viewport without losing the disclosure semantics. Tabs declared on a class *without* `@AutoLayout` still carry their `groupRelationship`, but are marked `adaptable: false` — the developer asked for tabs, so tabs they get. ## The limits of inference Inference has a ceiling, and it is **not an implementation gap that a future version will close** — it is a limit on what your model contains. Knowing where it sits saves you waiting for something that cannot arrive. Mateu infers **presentation from shape**. It can do that because shape and presentation are tightly correlated: six short optional fields *are* a foldable group; a class of `MetricCard` fields *is* a dashboard. Page **family**, though, comes from a different place. The Redwood decision model that the six families come from starts at the **user's goal**: ``` user goal → category → data density → template → fixed anatomy ``` Mateu starts at the **data model**. That distance is the ceiling. A list of records could be a table, a calendar, a kanban, a planning board or a triage queue — **the same shape, five different user goals**. No amount of inference separates them, because the information is not in the model. So Mateu only composes the families that are **fully derivable** from what you declared (`MetricCard` fields → Dashboard; a page of `Button` calls-to-action → Welcome). For everything else it can at most *hint* — the advisor logs "this looks like a CollectionDetail" — and **you** pick, which is exactly what [The Mateu Way](/the-mateu-way/) asks you to do first. That is not a limitation to work around. It is the one decision the framework needs from you, and it takes one annotation. ## Notes - The decision table lives in `LayoutInference` (core, `componentmapper`), and it is the **reference implementation**: the C# and Python backends port the exact same rules and thresholds, so the wire JSON is identical whichever server emits it. - The thresholds are constants of that class: `RADIO_MAX_OPTIONS = 4`, `FOLD_WEIGHT_THRESHOLD = 16`, `FOLD_MIN_OPTIONAL = 4`, `TABS_MIN_SECTIONS = 5`, `TABS_WEIGHT_THRESHOLD = 30`. - Behaviour is asserted end to end in `LayoutInferenceSyncTest` (core), including that classes **without** `@AutoLayout` keep the exact previous rendering. ## When to use it Put `@AutoLayout` on forms and record views whose layout you have no strong opinion about — quickly-built back-office screens, generated CRUD models, prototypes — and keep hand-tuned layouts (`@Zones`, `@Toc`, sticky sections, explicit tabs) for the screens you designed deliberately. Since explicit annotations always win, it is safe to enable globally with `mateu.layout.inference.enabled=true` and refine individual screens later. ## Global switches Both kinds of inference have one global switch each, named the same way. An annotation on the class (`@AutoLayout(…)` / `@AutoPage(…)`) always wins over the switch. | Inference | Java (system property, or the env var) | C# (`AppContext` switch) | Python (env var) | Default | |---|---|---|---|---| | Layout (`@AutoLayout`) | `mateu.layout.inference.enabled` / `MATEU_LAYOUT_INFERENCE_ENABLED` | `Mateu.LayoutInference.Enabled` | `MATEU_LAYOUT_INFERENCE_ENABLED` | `false` | | Page (`@AutoPage`) | `mateu.page.inference.enabled` / `MATEU_PAGE_INFERENCE_ENABLED` | `Mateu.PageInference.Enabled` | `MATEU_PAGE_INFERENCE_ENABLED` | `true` | The names used before 3.0-alpha.412 still work, but they are deprecated and log one warning naming the replacement: `mateu.layout.inference` (C# `Mateu.LayoutInference`) and `mateu.page.inference.disabled` (C# `Mateu.PageInference.Disabled`) — mind that one: `disabled=true` means `enabled=false`. When both an old and a new name are set, the new one wins. --- # Ledger URL: https://mateu.io/ux-patterns/ledger/ > A folio/receipt breakdown — concept lines, included items, discounts and a big total. **Status:** ✅ Implemented ## Intent Show the money breakdown behind a total — a hotel folio at check-out, an invoice preview, an order summary — as clean concept/amount lines the customer can verify at a glance, with discounts and included items visually distinct. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Ledger` component: a `currency` symbol, a `totalLabel`, a list of `LedgerLine`s and an optional `total`. Each line has a `concept` and either an `amount` (right-aligned monospace, formatted `€ 1.540,00`; negative amounts render error-red) or `included(true)` with an optional `includedLabel` (default "Included") shown muted instead of a figure. When `total` is absent the client computes the sum of the non-included amounts. ```java @Section("Folio") Component folio = Ledger.builder() .currency("€").totalLabel("Total") .lines(List.of( LedgerLine.builder().concept("Alojamiento x7 noches").amount(1540.0).build(), LedgerLine.builder().concept("All Inclusive Package") .included(true).includedLabel("Incluido").build(), LedgerLine.builder().concept("Descuento Platinum -10%").amount(-154.0).build())) .total(1710.5) .build(); ``` ![Ledger](/images/docs/ledger/ledger.png) All formatting (thousands separator, two decimals, currency symbol) happens client-side like the money stereotype. The component is display-only — it dispatches no actions; pair it with a [Payment picker](/ux-patterns/payment-picker/) for the charge itself. ## When to use it Use a `Ledger` wherever the user must **verify a monetary breakdown before committing** — check-out, order confirmation, refund review. For plan/tier comparison use a [Pricing table](/ux-patterns/pricing-table/); to track the balance against a limit while charges accrue use a [Meter](/ux-patterns/meter/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/ledger-demo`. --- # Live header values URL: https://mateu.io/ux-patterns/live-header-values/ > Values on the app header — a business date, a shift — that the server changes while the app is open, in every tab and, opt-in, in every open session. **Status:** ✅ Implemented · `@Experimental` ![The business date and the shift on the app header](/images/docs/live-header-values/header.png) ## Intent Operational apps show a few facts on the header that everybody works against: the hotel's **business date**, the current **shift**, a cut-off. They change rarely but for everyone at once — the night audit moves the business date, and a front desk still showing yesterday's date is a real error. A header widget built when the shell loads goes stale until the next reload. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The app class supplies the values; each has an `id` the server addresses it by: ```java @App(liveUpdates = true) public class Shell implements HeaderValuesSupplier { @Override public List<HeaderValue> headerValues(HttpRequest httpRequest) { return List.of( new HeaderValue("businessDate", "Business date", hotel.businessDate()), new HeaderValue("shift", "Shift", shifts.current())); } } ``` Then change one in either of two ways: | From | How | Who sees it | |---|---|---| | an action's answer | `return UICommand.updateHeaderValue("shift", "Night");` | this tab and the other tabs of the same browser | | anywhere on the server | `LiveHeaderValues.publish("businessDate", "13 Oct 2026");` | every open session of the app — with `@App(liveUpdates = true)` | ```java @Toolbar public Object closeTheDay() { var next = hotel.closeDay(); LiveHeaderValues.publish("businessDate", next); // every session, including this one return new Message("Day closed"); } ``` A change is announced to screen readers ("Business date changed to 13 Oct 2026") and flashes briefly on the header (not with reduced motion). ### How it travels — and why it is cheap - **Tabs of one browser** share changes through `localStorage` (the `storage` event): a tab that learns a new value tells the others. No request. - **Other sessions**: with `liveUpdates`, each **browser** keeps **one** event stream open — not one per tab. The tabs elect a leader through `localStorage` (a heartbeat every 5 s; a silent leader is replaced after 15 s), only the leader holds the stream, and it hands each change to the other tabs. That matters: browsers allow about six connections per host over HTTP/1.1, and a stream per tab would starve the app's own requests. - The stream is the **existing** SSE endpoint every adapter already has (`/mateu/v3/sse/…`) running the app-level `_live-updates` action — no new endpoint, no polling. It sends the last value published for each id first (a reconnecting browser catches up), then every publish, and an empty heartbeat every 20 s for proxies. The server ends it every 5 minutes on purpose and the browser reconnects at once; that bounds the life of a stream whose browser went away without the adapter noticing. - A shell built after a publish starts from the published value. `LiveHeaderValues` is **in-process**: a publish reaches the sessions connected to that server. In a cluster, publish on every node (e.g. from the message listener that learns about the change). It is all opt-in: without `HeaderValuesSupplier` there is nothing on the header, and without `liveUpdates` no stream is opened. ### In YAML ```yaml type: AppShell liveUpdates: true headerValues: - id: businessDate label: Business date value: 12 Oct 2026 ``` A static bundle carries the values but never a stream (there is no server to stream from). ## Where it works - **Vaadin** — on the header next to the app-context pickers (`mateu-header-values`). - **Redwood (Oracle VB)** — in the shell header, with the same tab sharing and one-stream-per-browser rule. - **React Native** — at the top of the drawer; the stream while the app is in the foreground. - **IntelliJ plugin** — at the top of the navigator; one background stream per session. - Also from the C# (`IHeaderValuesSupplier`, `LiveHeaderValues.Publish`) and Python (`HeaderValuesSupplier`, `LiveHeaderValues.publish`) backends — both serve the same `/mateu/v3/sse/…` stream. Demo: `demo-admin-panel` → **End of day** (`/e2-business-day`, F8): *Close the day* publishes, *Change shift* answers a command. Open `/` in another tab and `/e2-demo` in another browser to watch both. ## Related - [App context](/ux-patterns/app-context/) — a value the USER picks for every screen - [Long-running jobs](/ux-patterns/long-running-jobs/) — the same SSE endpoint --- # Long-Running Jobs URL: https://mateu.io/ux-patterns/long-running-jobs/ > Give a dignified UX to asynchronous processes without freezing the interface. **Status:** ✅ Implemented — `LongTask`, `Flux<?>`, `@Action(background)` ## Intent Give asynchronous processes a dignified UX without freezing the interface. ## Problem A process that takes seconds or minutes and blocks the entire screen is the *Spinner Prison*: the user cannot do anything and does not know if the system is still alive. Long operations must be launched, tracked, and reacted to without a hard block. ## Solution Mateu offers three strategies depending on how much feedback the operation can provide: | Strategy | When to use | |---|---| | `LongTask` + `Flux<?>` | Operation emits incremental steps; show a live progress dialog | | `Flux<?>` (low-level) | Need full control over what is streamed to the client | | `@Action(background = true)` | Fire-and-forget; the UI stays interactive, no progress shown | ### How streaming is wired: `Flux` ⇔ `sse` Returning a `Flux<?>` **is** the switch that turns on SSE streaming: the framework detects the `Flux` return type and enables `sse` automatically, so you rarely write `@Action(sse = true)` by hand (`LongTask.run(...)` returns a `Flux`, so it streams too). Under the hood every action produces a `Flux<UIIncrementDto>` — a non-streaming action emits a single item, a streaming one emits many over the same SSE channel. `background` is a **separate, orthogonal** flag: it only tells the frontend not to show the busy indicator (a fire-and-forget feel). It does not stream and is not needed for streaming. The two concerns are independent: | Concern | Control | |---|---| | Stream many updates vs one response | return a `Flux<?>` (auto-enables `sse`) — or `@Action(sse = true)` | | Show the busy indicator vs fire-and-forget | `@Action(background = …)` | --- ## `LongTask` — live progress dialog :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: `LongTask` is the high-level API for streaming progress to a modal dialog. Return the result of `LongTask.run(...)` directly from a `@Button` method: ```java @Button @Action(validationRequired = false) public Flux<?> generateReport() { return LongTask.create("Generating report...") .done("Done", "Report generated") .run(progress -> reportService.generateWithProgress() .map(step -> progress.step(step.message()))); } ``` Internally, `LongTask` composes a `Flux.concat` of three segments: 1. **Opening event** — sends a dialog component to the frontend, showing the progress dialog. 2. **Work flux** — your flux, streamed live as each `progress.step(...)` is emitted. 3. **Closing event** — updates the dialog to its final state and dispatches any configured commands. ### `LongTask` builder methods | Method | Description | |---|---| | `LongTask.create(title)` | Opens the dialog with the given header title | | `.done(doneTitle, doneText)` | Sets the header and body shown when the flux completes | | `.withProgressBar()` | Adds a determinate progress bar to the dialog | | `.closeAfter(seconds)` | Auto-closes the dialog N seconds after completion | | `.withCommand(commands…)` | Dispatches `UICommand`s when the task completes | | `.run(work)` | Builds the flux; returns this to the `@Button` method | ### Updating progress with `ProgressReporter` The `work` lambda receives a `ProgressReporter`. Each call to `step(...)` returns the SSE payload that must be emitted by the flux — it is not a side-effect: ```java LongTask.create("Processing...") .run(progress -> items .map(item -> progress.step("Processing: " + item.name()))); ``` `ProgressReporter` offers four overloads: | Signature | Updates | |---|---| | `step(text)` | Dialog body text | | `step(text, title)` | Dialog body text + header title | | `step(text, progress)` | Dialog body text + progress bar (0.0 – 1.0) | | `step(text, title, progress)` | Dialog body text + header title + progress bar | ### Progress bar Add `.withProgressBar()` to show a determinate progress bar. Pass a `double` between `0.0` and `1.0` as the progress argument to `step()`. The bar automatically fills to `1.0` when the flux completes. ```java @Button @Action(validationRequired = false) public Flux<?> importData() { return LongTask.create("Importing data...") .withProgressBar() .done("Done", "Import complete") .run(progress -> importService.rows() .map(row -> progress.step( "Imported: " + row.name(), row.index() / (double) row.total()))); } ``` ### Auto-closing the dialog Add `.closeAfter(seconds)` to close the dialog automatically once the task finishes, without requiring the user to dismiss it manually. Useful for fire-and-forget operations where the final message is informational: ```java LongTask.create("Importing data...") .withProgressBar() .done("Done", "Import complete") .closeAfter(3) .run(progress -> importService.rows() .map(row -> progress.step("Imported: " + row.name()))); ``` ### Running a command on completion Add `.withCommand(UICommand...)` to execute one or more UI commands when the task finishes. Commands run immediately after the dialog is updated to its final state, before any auto-close timer fires. Multiple commands are supported: ```java LongTask.create("Importing data...") .withProgressBar() .done("Done", "Import complete") .closeAfter(2) .withCommand(UICommand.navigateTo("/results")) .run(progress -> importService.rows() .map(row -> progress.step("Imported: " + row.name()))); ``` Available commands and their behaviour from a dialog element: | Command | Works | Notes | |---|---|---| | `UICommand.navigateTo(url)` | ✅ | Changes `window.location.href`; relative and absolute URLs | | `UICommand.pushStateToHistory(url)` | ✅ | Pushes a history entry without full reload | | `UICommand.dispatchEvent(name, detail)` | ✅ | Dispatches a custom DOM event that bubbles up | | `UICommand.runAction(actionId, targetId)` | ✅ | Triggers an action on a specific component | | `UICommand.runAction(actionId)` | ⚠️ | Requires the dialog to handle action events; prefer the two-arg form | | `CloseModal` | ❌ | Use `.closeAfter(seconds)` instead | ### Validation If the action reads form fields, validation runs before the method is called by default. Add `@Action(validationRequired = false)` to skip it — common for operations that don't depend on the current form values: ```java @Button @Action(validationRequired = false) public Flux<?> doSomethingLong() { ... } ``` --- ## Low-level `Flux<?>` streaming When you need full control over what is streamed, return a `Flux<?>` directly and emit any supported UI effect type. The framework maps each emitted value to an SSE event and sends it to the client: ```java @Button public Flux<?> streamResults() { return service.processItems() .map(item -> Message.info("Processed: " + item.name())) .concatWith(Flux.just(Message.success("All done"))); } ``` Supported emit types include `Message`, `UICommand`, `UIFragmentDto`, `UIIncrementDto`, and any object that the reflection mapper can convert to a component. --- ## Non-blocking launch Set `background = true` to start the job and return immediately. The UI stays interactive; no progress dialog is shown. Use this for operations where the outcome is reported separately (e.g. via email, a refresh, or polling). ```java @Button @Action(background = true) public void generateReport() { reportService.generate(); } ``` --- ## Polling with `@Trigger` When push is not available, use `@Trigger` to poll for state at regular intervals: ```java @Trigger(type = TriggerType.OnLoad, actionId = "checkStatus", times = 20, timeoutMillis = 3000) public class ReportStatus { @Hidden String jobId; @Autowired JobService jobService; public JobStatus checkStatus() { return jobService.getStatus(jobId); } } ``` --- ## Structure Progress dialog while running: ``` ┌──────────────────────────────────────┐ │ Generating report... ✕ │ ├──────────────────────────────────────┤ │ Processing record 1,234 of 1,841 │ │ ████████████████░░░░░░░░░░ 67% │ └──────────────────────────────────────┘ ``` Dialog after completion (with `.done()`): ``` ┌──────────────────────────────────────┐ │ Done ✕ │ ├──────────────────────────────────────┤ │ Report generated │ │ ██████████████████████████ 100% │ └──────────────────────────────────────┘ ``` --- ## Principles served - **Preserve context** — the rest of the UI stays usable while the job runs - **Feedback** — the user sees live progress rather than a frozen screen - **Recoverability** — the user can close the dialog; errors surface as actionable feedback - **Consistency** — progress and outcome feedback follow the same pattern everywhere --- # Matrix grid URL: https://mateu.io/ux-patterns/matrix-grid/ > Rows of metrics or types by columns of dates, in collapsible sections, with cells that open an action and rows edited in place — the shape of an availability or forecast grid. **Status:** ✅ Implemented ![A matrix grid: availability per room type and day, in collapsible sections](/images/docs/matrix-grid/property-availability.png) ## Intent Some screens are not a list of records but a **matrix**: what you are looking at is a value at the crossing of a row (a metric, a room type, a product) and a column (a date). Hotel availability, a sales forecast, a staffing plan. A listing grid cannot say "click *this* cell" or "edit the value for Tuesday", and a form has no columns. OPERA Cloud's **Property Availability** is the reference: house totals, availability by room type and controls by date, sections that fold, figures that open the day, and an overbooking row edited in place. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Return a `MatrixGrid`: ```java MatrixGrid.builder() .rowHeaderLabel("Room type") .cellActionId("openDay") // a link cell runs it .editActionId("setOverbooking") // an edited cell commits through it .columns(dates.stream().map(d -> new MatrixColumn( d.toString(), "Sat 17", "Oct 2026", weekend(d) ? "neutral" : null)).toList()) .sections(List.of( MatrixSection.builder().id("types").title("Availability by room type").rows(List.of( MatrixRow.builder().id("STD").label("STD").cells(List.of( new MatrixCell("8", null, true), new MatrixCell("-1", "danger", true))).build())).build(), MatrixSection.builder().id("controls").title("Controls").collapsed(true).rows(List.of( MatrixRow.builder().id("ob:STD").label("Overbooking STD").editable(true) .cells(List.of(MatrixCell.of(0), MatrixCell.of(2))).build())).build())) .build(); ``` Both actions receive the cell as parameters — `_rowId`, `_columnId`, `_value` — so the `@Action` method knows which cell it was: ```java @Action public Object setOverbooking(HttpRequest rq) { var p = rq.runActionRq().parameters(); overbooking.put(p.get("_rowId") + "@" + p.get("_columnId"), Integer.parseInt((String) p.get("_value"))); return this; // re-render: the availability rows recompute } ``` ### The pieces | Record | Holds | |---|---| | `MatrixColumn(id, label, group, tone)` | consecutive columns with the same `group` (the month) get a spanning header; `tone` tints the column (weekends) | | `MatrixSection(id, title, collapsed, rows)` | a collapsible group of rows; a blank `title` puts its rows at the top level | | `MatrixRow(id, label, cells, editable, emphasis)` | one cell per column (the server pads or cuts to the column count); `editable` cells are edited in place; `emphasis` for totals | | `MatrixCell(value, tone, link)` | `tone` — `info`, `success`, `warning`, `danger`, `neutral` — wins over the column's; `link` runs `cellActionId` | Folding sections is client-side state and survives the re-render that follows an edit. An edit that leaves the value unchanged sends nothing. ## Where it works - **Redwood (Oracle VB)** — painted by JET's own **`oj-data-grid`** over a `RowDataGridProvider`: the sections are tree rows with JET's disclosure icons, the month a nested column header, and editing is the grid's cell edit mode (F2 / Enter / typing; non-editable cells are read-only through `cell.editable`). - **Vaadin** — the shared `mateu-matrix-grid` element (sticky headers and row labels; double click, Enter or F2 to edit; Escape cancels). - **React Native** and the **IntelliJ plugin** — a fixed label column with horizontally scrolling cells / a `JBTable` with a row header. - Also available from the C# (`new MatrixGrid { … }`) and Python (`fluent.MatrixGrid(…)`) backends. ## Related - [Planning board](/ux-patterns/planning-board/) — resources × days with draggable bars, when the cells are bookings rather than figures - [Editable table](/ux-patterns/editable-table/) — editing records, not a matrix of values --- # Meter URL: https://mateu.io/ux-patterns/meter/ > Consumption against a limit — a formatted value, a progress track and warn/danger thresholds. **Status:** ✅ Implemented ## Intent Show how much of a limit has been consumed — a folio balance against a preauthorization, storage against a quota, budget spent against allocated — so the operator sees the value *and how close it is to the ceiling* in one glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Meter` component: a small-caps `label`, a numeric `value` and `max`, an optional `unit` symbol (appended after the formatted number: `1.240,00 €`), a muted `caption`, and optional `warnAt` / `dangerAt` thresholds. The fill is `value / max` clamped to 0..1; its color is success below `warnAt`, warning at or above it, and error at or above `dangerAt` (no thresholds → primary color). When `caption` is empty the computed fill percentage is shown instead. ```java @Section("Folio") Component balance = Meter.builder() .label("BALANCE ACTUAL") .value(1240.0).max(1800.0).unit("€") .caption("69% de la preautorización consumido") .warnAt(1440.0).dangerAt(1710.0) .build(); ``` ![Meter](/images/docs/meter/meter.png) The value is formatted client-side like the money stereotype (thousands separator, two decimals). The component is display-only — it dispatches no actions. The renderer is dependency-free, themes through the standard CSS variables and works in dark mode. ## When to use it Use a `Meter` when a value is only meaningful **relative to a limit** — balance vs preauthorization, occupancy vs capacity, usage vs quota. For a metric with a trend and sparkline use [Stat](/ux-patterns/stat/); for dashboard tiles use `MetricCard` inside a [Dashboard](/ux-patterns/dashboard/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/meter-demo`. --- # Mobile App (Open on Mobile) URL: https://mateu.io/ux-patterns/mobile-app/ > One generic Mateu app for iOS and Android that renders any Mateu UI natively — UIs are added by scanning a QR code, like accounts in an authenticator app. The server side (the UI manifest and the "Open on mobile" button) ships today. **Status:** 🧪 Experimental (`@Experimental`, mobile app 3.0 beta) — phase 1 (server + web) is shipped; the app itself is on its way (see [Status](#status)). ## Intent A Mateu UI already renders natively: the React Native renderer speaks the same `/mateu/v3/*` wire as the web renderers. What is missing is a way to *get* a UI onto a phone without building and publishing an app per UI. The answer is **one** generic app, "Mateu", in the App Store and Google Play, to which users **add UIs by scanning a QR code** — exactly the way Google Authenticator adds accounts. | Google Authenticator | Mateu app | |---|---| | QR `otpauth://totp/Issuer:user?secret=…&issuer=…` | QR `https://mateu.io/add?u=<baseUrl>` (universal link) or `mateu://add?u=<baseUrl>` | | an "account" = issuer + user + icon | a "UI" = name + base URL + icon (from the server's manifest) | | local list, no Google account | local list, no "Mateu" account | | add by QR or by typing the key | add by QR or by typing the URL | | remove, reorder, search | the same, plus selecting which UI is open | | "Transfer accounts" (export QR) | "Export my UIs" QR: the list of URLs only, never sessions or tokens | **The key difference:** an authenticator QR carries a *secret*; ours carries **none** — only the URL. Credentials are entered at login (OIDC). A photographed or forwarded QR grants nothing: at worst it adds an entry to someone's list. ## The UI manifest Every UI answers a small, public, cacheable description of itself: ``` GET <baseUrl>/mateu/v3/manifest ``` (`/mateu/v3/manifest` for a UI mounted at the root.) It is served by the five Java adapters (Spring MVC, WebFlux, Micronaut, Quarkus, Helidon MP — for `@UI` classes and YAML mounts alike), by ASP.NET Core and by FastAPI, with `Content-Type: application/json`, `Cache-Control: public, max-age=300` and `X-Content-Type-Options: nosniff`. ```json { "name": "Acme CRM", "shortName": "CRM", "icon": "/images/acme.svg", "themeColor": "#1f6feb", "wireVersion": "3.0", "minAppVersion": "1.0.0", "auth": { "type": "oidc", "issuer": "https://auth.acme.com/realms/acme", "clientId": "mateu-mobile", "scopes": ["openid", "profile"] } } ``` A member with no value is **omitted**, never `null`. Name, icon and colour come from the app itself, so a rename or a new icon reaches every phone without anybody re-scanning. An `icon` may be relative: the app resolves it against the manifest's URL. ### Where each member comes from Highest precedence first. A **setting** is, in Java, a JVM system property (`mateu.mobile.…`), a key in the framework's configuration (`application.properties`, MicroProfile Config…) or the matching environment variable (`MATEU_MOBILE_…`); in .NET and Python, the environment variable. Settings win because the identity provider usually changes per environment while the code does not. | Member | Setting (env var) | `@MobileApp` / `[MobileApp]` / `@mobile_app` | Fallback | |---|---|---|---| | `name` | `MATEU_MOBILE_NAME` (`mateu.mobile.name`) | `name` | the app's title (`@Title`; `[App("…")]`; `@app("…")`), else the humanized class name | | `shortName` | `MATEU_MOBILE_SHORT_NAME` | `shortName` / `ShortName` / `short_name` | = `name` | | `icon` | `MATEU_MOBILE_ICON` | `icon` | Java: the app's `@Logo`, else its `@FavIcon`; else omitted | | `themeColor` | `MATEU_MOBILE_THEME_COLOR` | `themeColor` / `ThemeColor` / `theme_color` | Java: `@App(accentColor)`; else omitted | | `wireVersion` | — | — | the server's wire version, the same value every response carries (`"3.0"`; servers before 3.0-alpha.426 sent `"3"` — the app compares the major only, so both are the same wire) | | `minAppVersion` | `MATEU_MOBILE_MIN_APP_VERSION` | `minAppVersion` / `MinAppVersion` / `min_app_version` | `"1.0.0"` | | `auth.issuer` | `MATEU_MOBILE_OIDC_ISSUER` | `oidcIssuer` / `OidcIssuer` / `oidc_issuer` | — | | `auth.clientId` | `MATEU_MOBILE_OIDC_CLIENT_ID` | `oidcClientId` / `OidcClientId` / `oidc_client_id` | — | | `auth.scopes` | `MATEU_MOBILE_OIDC_SCOPES` (comma and/or space separated) | `scopes` / `Scopes` / `scopes` | `["openid", "profile"]` | :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: `auth` is emitted only when **both** the issuer and the client id resolve; blank values count as unset. The .NET and Python ports have no app logo, favicon or accent colour, so there `icon` and `themeColor` come only from `MobileApp` or the environment. ```java @UI("/crm") @Title("Acme CRM") @Logo("/images/acme.svg") @App(mobileQr = true) @MobileApp(shortName = "CRM", themeColor = "#1f6feb", oidcIssuer = "https://auth.acme.com/realms/acme", oidcClientId = "mateu-mobile") public class AcmeCrm { } ``` ```csharp [App("Acme CRM", MobileQr = true)] [MobileApp(ShortName = "CRM", Icon = "/images/acme.svg", ThemeColor = "#1f6feb", OidcIssuer = "https://auth.acme.com/realms/acme", OidcClientId = "mateu-mobile")] public class AcmeCrm { } ``` ```python @app("Acme CRM", mobile_qr=True) @mobile_app(short_name="CRM", icon="/images/acme.svg", theme_color="#1f6feb", oidc_issuer="https://auth.acme.com/realms/acme", oidc_client_id="mateu-mobile") class AcmeCrm: ... ``` A YAML-only deployment (a `type: UI` mount) gets its name, icon and colour from its app shell and the rest from the settings. :::note[Settings are JVM properties or environment variables] In Java the settings are read the way Mateu's other switches are (`MateuSettings`): a JVM system property (`-Dmateu.mobile.oidc.issuer=…`) or the environment variable (`MATEU_MOBILE_OIDC_ISSUER`). A key in Spring's `application.properties` or Quarkus' `application.properties` is **not** read — set the environment variable in each environment's deployment instead. ::: :::caution[Secured apps: let the manifest through] The phone fetches the manifest **before** anyone has signed in. If your application protects every path (Spring Security, Quarkus OIDC, an API gateway…), permit anonymous `GET` on `<baseUrl>/mateu/v3/manifest` of each UI, e.g. `.requestMatchers(HttpMethod.GET, "/crm/mateu/v3/manifest").permitAll()`. ::: ## Open on mobile `@App(mobileQr = true)` adds an **"Open on mobile"** button to the app header. The same switch is `mobileQr: true` on a YAML [`type: AppShell`](/define/yaml/app-shell/), `[App(MobileQr = true)]` in .NET and `@app(mobile_qr=True)` in Python; it travels as `AppDto.mobileQr`. It is opt-in: without it nothing changes. On a desktop the button opens a dialog with the **QR code** of the link to this app — at the screen being shown — the link as copyable text and a short hint. On a phone (a narrow or touch-only screen) there is nothing to scan, so it shows an **"Open in the Mateu app"** link instead. The link is: ``` https://mateu.io/add?u=<url-encoded absolute base URL>[&r=<url-encoded route>] ``` - `u` is the page's origin plus the mount's base URL (`https://crm.acme.com/crm`). - `r` is the current route relative to the mount (`/orders/42?tab=lines`), omitted on the home screen. - The app also accepts the same query on `mateu://add?…`. It is a universal link (iOS) / App Link (Android): the phone's camera opens the Mateu app when it is installed, and otherwise lands on [mateu.io/add](/add/), which shows the target domain, the store links and the QR again. The QR is drawn in the browser by a small dependency-free encoder that ships with Mateu (no third-party code, no network call): the Vaadin and Redwood renderers both have it, loaded only when the dialog opens. ## Security - **No secrets in a QR**, nor in the "export my UIs" QR: only URLs. Tokens never leave the phone's secure store. - **HTTPS only.** The app refuses plain-HTTP UIs (a development build can allow `localhost`). - **Adding requires confirmation**, showing the **domain** prominently next to the manifest's name and icon. A QR can come from anyone; this is the phishing protection. - **Mateu never validates tokens.** The app signs in with OIDC (Authorization Code + PKCE, in the system browser) against the issuer the manifest names, keeps one session per UI and sends `Authorization: Bearer` on every call. The *host application's* framework (Spring Security, Quarkus OIDC, ASP.NET authentication…) validates the token, exactly as for the web renderers; the manifest only tells the client which identity provider the host trusts. - The manifest is public by design: it says what the UI is called and where to log in, nothing more. Keep anything sensitive out of `name` and `icon`. - The wire and app versions are checked: a UI that needs a newer app shows "Update the app". ## Status The plan has four phases (see `design/mobile-app-hub.md` in the repository): 1. **Server** — the manifest on every backend and "Open on mobile" on the Vaadin and Redwood renderers. **Shipped (experimental).** 2. **App MVP** — the list of UIs (add by URL or QR, remove, reorder), opening a UI, per-UI OIDC, universal links, the export QR. **Built (experimental)**, in internal builds until the store release. 3. **Store release** — listings, a reviewer demo, privacy labels. 4. **Enterprise** — managed configuration (MDM) with a pushed or locked list of UIs, signed QR codes, a domain allow-list; then push notifications through the [notification inbox](/ux-patterns/notification-inbox/). Until the app is in the stores, the QR leads to the landing page, which says so. --- # Navigation & Menus URL: https://mateu.io/ux-patterns/navigation/ > Navigation patterns for business applications — from flat tabs to deep multi-level structures. Navigation is the skeleton of a backoffice application. A poorly chosen navigation pattern forces users to memorise structure instead of doing work. Mateu selects a navigation style automatically based on menu structure, and lets you override it when the inference is wrong. ## How Mateu selects the navigation style By default, Mateu applies this inference chain: ``` Menu federates a RemoteMenu → Top navigation bar Menu has submenus (> 2 levels) → Tiles hub (top nav + card grid at the depth boundary) Menu has submenus and > 7 top-level entries → Hamburger menu Menu has submenus (≤ 2 levels) → Top navigation bar Menu has no submenus → Tabs ``` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: You can override the inference at any point with `@App`: ```java @App(AppVariant.MENU_ON_LEFT) public class MyAdminApp { ... } ``` --- ![Menu app — navigation bar with top-level tabs](/images/docs/build/navigation.png) ## Pattern catalogue ### Tabs **Status:** ✅ Implemented — `AppVariant.TABS` The default for applications with a flat, shallow menu (no submenus). Each top-level section is a tab. Best for 3–8 peer sections with no hierarchy. ``` ┌──────┬──────────┬──────────┬──────────┐ │ Home │ Products │ Orders │ Reports │ └──────┴──────────┴──────────┴──────────┘ Content area ``` **When to use:** Flat apps, dashboards, tools with few sections. --- ### Top navigation bar **Status:** ✅ Implemented — `AppVariant.MENU_ON_TOP` The default for applications with up to two levels of menu hierarchy. Section groups appear as top-level items; subsections drop down on hover or click. ``` [Logo] Catalogue ▾ Operations ▾ Reports ▾ Settings ▾ ├ Products ├ Orders ├ Sales ├ Categories ├ Shipments └ Inventory └ Brands └ Returns ``` **When to use:** Standard backoffice apps with 2-level structure. --- ### Sidebar (left navigation) **Status:** ✅ Implemented — `AppVariant.MENU_ON_LEFT` A vertical left panel with collapsible section groups. Keeps the full navigation tree visible and persistent while the user works, at the cost of horizontal space. ``` ┌──────────────┬─────────────────────────────┐ │ ▼ Catalogue │ │ │ Products │ Content area │ │ Categories │ │ │ Brands │ │ │ ▶ Operations │ │ │ ▶ Reports │ │ │ ▶ Settings │ │ └──────────────┴─────────────────────────────┘ ``` **When to use:** Apps where users jump frequently between sections; data-dense environments where tab/top-bar switching is disorienting. ```java @App(AppVariant.MENU_ON_LEFT) public class MyAdminApp { ... } ``` --- ### Hamburger / Drawer **Status:** ✅ Implemented — `AppVariant.HAMBURGER_MENU` Navigation is hidden behind a hamburger icon and slides in as a drawer. Maximises content space. Standard on mobile; acceptable on desktop for infrequently accessed sections. ``` ☰ [Logo] [App title] [User ▾] ``` ``` ┌──────────────┐ │ ✕ Menu │ │ ───────── │ │ Home │ │ ▼ Catalogue │ │ Products │ │ Categories │ │ Operations │ │ Reports │ └──────────────┘ ``` **When to use:** Mobile-first apps; dense single-page tools where navigation is secondary to the content. --- ### Navigation rail **Status:** ✅ Implemented — `AppVariant.RAIL` A slim 72px vertical strip with icon and short label per item. Items with children open a 200px secondary panel listing their children. Narrower than the full sidebar; ideal for users who know the sections well. ``` ┌────┬─────────────────────────────┐ │ 🏠 │ │ │Home│ Content area │ │ │ │ │ 📦 │ │ │Cat.│ │ │ │ │ │ 🛒 │ │ │Ops │ │ └────┴─────────────────────────────┘ ``` With a parent item open: ``` ┌────┬────────────┬────────────────┐ │ 🏠 │ Operations │ │ │Home│ ────────── │ Content area │ │ │ Orders │ │ │ 📦 │ Shipments │ │ │Cat.│ Returns │ │ │ │ │ │ │ 🛒 │ │ │ │Ops │ │ │ └────┴────────────┴────────────────┘ ``` **When to use:** Apps targeting users who know the sections well and want compact navigation; hybrid desktop/tablet layouts. ```java @App(AppVariant.RAIL) public class MyAdminApp { ... } ``` Items without an `icon` field show the first letter of the label in a circle as fallback. --- ### Tiles hub **Status:** ✅ Implemented — `AppVariant.TILES` (also auto-inferred for depth > 2) A top nav bar where clicking an item with children shows a responsive card grid instead of a dropdown. Each card displays the section's label and optional description. Clicking a card navigates into that section; if the card itself has children, another tiles hub is shown. ``` [Logo] Catalogue Operations Reports Settings Operations ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Orders │ │ Shipments │ │ Returns │ │ │ │ │ │ │ │ Manage and │ │ Track and │ │ Process │ │ search POs │ │ dispatch │ │ refunds │ └──────────────┘ └──────────────┘ └──────────────┘ ``` **When to use:** Apps with 3+ levels of menu depth where dropdowns become unwieldy; home/dashboard landing pages. Tile descriptions are populated via `@Menu(description = "...")`: ```java @Menu(description = "Manage and search purchase orders.") private OrdersSection orders; @Menu(description = "Track dispatched shipments and update delivery status.") private ShipmentsSection shipments; ``` **Automatic inference:** when Mateu detects that any top-level menu item has grandchildren (depth > 2), it automatically selects `TILES` without any annotation. --- ### Deep-menu rule (> 2 levels) **Status:** ✅ Implemented When a menu exceeds two levels of depth, Mateu automatically switches to the `TILES` variant. The top-level items appear in the nav bar as flat (no dropdowns); clicking one with children shows a tiles hub in the content area. ``` Top nav: Home | Catalogue | Operations | … Click "Operations" → shows tiles hub in content area ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Orders │ │Shipments │ │ Returns │ └──────────┘ └──────────┘ └──────────┘ ``` The inference happens in `AppMetadataExtractor`: if any `Menu` item contains children that are also `Menu` items (i.e. submenu depth ≥ 3), the variant is set to `TILES`. --- ### Command palette **Status:** ✅ Implemented — `⌘K` / `Ctrl+K`, available in all variants A keyboard-triggered overlay that lets users search and jump to any section by typing. Results show the item label and its breadcrumb path (e.g. `Operations › Shipments`). Always active — no opt-in required. ``` ┌─────────────────────────────────────────────┐ │ 🔍 Go to… │ │ ─────────────────────────────────────────── │ │ Orders Operations │ │ Shipments Operations │ │ Returns Operations │ │ Products Catalogue │ └─────────────────────────────────────────────┘ ``` **Keyboard controls:** | Key | Action | |---|---| | `⌘K` / `Ctrl+K` | Open / close | | Type | Filter results | | `↑` `↓` | Move selection | | `Enter` | Navigate to selected item | | `Escape` | Close | Results are sourced from the same menu tree used for the main navigation, flattened to leaf items only. --- ### Card menus (a group that opens as cards) **Status:** ✅ Implemented — Vaadin, Redwood, React Native and IntelliJ; Java, .NET, Python and YAML A menu **group** can open as a panel of **cards** instead of a plain dropdown, like the product menus of a documentation site. Each entry is a card with a **title** (its label), a **description**, and an **icon** or an **image**. An entry that holds entries of its own is not a destination: its entries become **actions** (links) on its card. ``` ┌ Bookings ▾ ─────────────────────────────────────────────────────────────┐ │ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ 📋 Check-in │ │ [floor plan image] │ │ 🧾 Billing │ │ │ │ Sign the registration│ │ Floor plan │ │ Folios, charges and │ │ │ │ card and scan the ID │ │ Rooms coloured by │ │ payments │ │ │ │ │ │ housekeeping status │ │ Folio · New booking │ │ │ └──────────────────────┘ └──────────────────────┘ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` Use it when a group's entries need a word of explanation to be chosen well: a launcher for occasional tasks, a product menu, a "quick access" group. Keep plain lists for the everyday navigation, where the label alone is enough. **YAML** (app shell) — `presentation` on the group and on its entries, `description` on each entry: ```yaml type: AppShell title: Front office variant: MENU_ON_TOP menu: - type: Menu label: Quick access presentation: {display: cards} submenu: - type: RouteLink label: Check-in route: check-in description: Sign the registration card and scan the ID presentation: {icon: "vaadin:clipboard"} - type: RouteLink label: Floor plan route: floor-plan description: Rooms coloured by housekeeping status presentation: {image: /img/floor.png} - type: Menu label: Billing description: Folios, charges and payments presentation: {icon: "vaadin:invoice"} submenu: # not a destination: these are the card's actions - {type: RouteLink, label: Folio, route: billing} - {type: RouteLink, label: New booking, route: bookings/new} ``` **Java**: ```java @Menu(display = MenuDisplay.cards) QuickAccess quickAccess; public class QuickAccess { @Menu(description = "Sign the registration card and scan the ID") @Icon(IconKey.Clipboard) RegistrationCard checkIn; @Menu(description = "Rooms coloured by housekeeping status", image = "/img/floor.png") FloorPlan floorPlan; @Menu(description = "Folios, charges and payments") @Icon(IconKey.Invoice) BillingActions billing; // its own @Menu entries become the card's actions } ``` In code-built shells (`MenuSupplier`, `AppSupplier`, fluent `AppShell`): `menu.withPresentation(MenuPresentation.cards())` on the group, and `withPresentation(MenuPresentation.card(icon, image))` / `withDescription(...)` on its entries. **.NET**: `[MenuGroup("Quick access", Display = MenuDisplay.Cards)]` + `[MenuItem(..., Description = ..., Icon = ..., Image = ...)]`. **Python**: `@menu_group("Quick access", display=MenuDisplay.cards)` + `@menu_item(..., description=..., icon=..., image=...)`. **Where it shows.** In the top navigation bars — `MENU_ON_TOP` and the section band of `HAMBURGER_SECTIONS` — on Vaadin and Redwood. React Native draws the cards inside its drawer (image, title, description and action chips); IntelliJ shows two-line rows with the icon and inline action links. The sidebar, drawer and rail variants on the web, and the narrow-viewport ☰ button, keep the plain list. A group without `display: cards` renders exactly as before. On Redwood a `vaadin:` icon with no Redwood equivalent shows a generic icon, so the cards stay aligned (an `image` shows as is everywhere). In the visual editor a group's **Display** select switches it to cards, and its entries get description, icon and image fields. Full reference: [Navigation and menus › Card menus](/java-user-manual/build/navigation-and-menus/#card-menus-a-group-that-opens-as-cards). --- ## Choosing a pattern | Situation | Recommended pattern | |---|---| | Flat app, 3–8 sections | Tabs | | Standard 2-level backoffice | Top navigation bar | | Frequent cross-section jumps, data-dense | Sidebar | | Mobile-first or navigation is secondary | Hamburger/Drawer | | Compact, icon-familiar users | Rail | | Deep menu (> 2 levels) | Tiles hub (auto-inferred) | | Power users, keyboard-heavy | Command palette (always available) | | A group whose entries need a description to be chosen | Card menu (`display: cards` on the group) | ## Combining patterns All variants include the command palette automatically — there is nothing to configure. For the main navigation, patterns are mutually exclusive (one `AppVariant` per app), but they compose naturally with other UX patterns: - **Tiles hub + Command palette** — deep apps where some users prefer keyboard, others prefer scanning cards - **Sidebar + Command palette** — complex apps where the sidebar gives orientation and the palette gives speed - **Rail + Command palette** — compact apps for expert users who want maximum content space --- # Not found URL: https://mateu.io/ux-patterns/not-found/ > A route whose record does not exist renders a not-found page in place of its content — throw NoSuchElementException with a user-facing message and Mateu does the rest, in every renderer. **Status:** ✅ Implemented ## Intent A link outlives what it points to. A booking is deleted, a customer is merged into another, an id is mistyped in a shared URL — and the user opens `/reservas/FO-X6JB7F`. The screen behind that route cannot load its record, and the worst answers are the common ones: an error toast over an empty page, or a stack trace in the log for something that is not a bug. The right answer is a page that says what happened — *this record is not here* — and offers a way back, inside the app's shell so the menu is still there. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: **Throw `java.util.NoSuchElementException` while the route loads**, with a message written for the user. Nothing else to do: no screen-by-screen handling. ```java @Override public Stay view(String id, HttpRequest httpRequest) { return stays.findById(id) .orElseThrow(() -> new NoSuchElementException("Booking " + id + " not found")); } ``` What counts as "while the route loads": the view's constructor, a `RouteHandler`, a `Navigable.view(id)`, a CRUD's `findById` for its detail or edit route, and the mapping of the loaded view — anything that runs for the initial load of a route (an empty action id, or `__load__`). Mateu then: - answers a **`NotFound` component** (`NotFoundDto {title, message, backRoute, backLabel}` on the wire) as the content of the route — not an error message. The renderers paint it in place of the page, keeping the app shell (top bar, menu) around it; - uses the exception's **message as the heading**; - logs **one INFO line** (`Not found: route /bookings/FO-X6JB7F — Booking FO-X6JB7F not found`) instead of an ERROR with a stack trace; - offers a **way back** to the parent route (`/bookings/FO-X6JB7F` → `/bookings`), or the app home for a top-level route. A route that resolves to **nothing at all** (no view, no definition) answers the same page, headed *Page not found* — it used to be a bare red `Not found.` text. ### The generic fallback When the exception carries no message — or carries `Optional.orElseThrow()`'s own *"No value present"*, which says nothing to a user — the heading is generic and names the missing id (the last segment of the route): **«No se ha encontrado FO-X6JB7F»** / **«Not found: FO-X6JB7F»**. The secondary line is *«Puede que se haya borrado o que el enlace no sea correcto.»* / *"It may have been deleted, or the link is wrong."*, and the way back reads *Volver* / *Go back*. The server picks Spanish or English from the request's `Accept-Language` (any other language gets English); the renderers fall back to the same texts in the page's language if a `NotFound` arrives without them. ### What it does not change - **Other exceptions** keep today's behaviour: an error message, and an ERROR log with the stack. - A `NoSuchElementException` thrown by an **action** (a button) on a screen that does exist is still an error message. Replacing the screen under the user's click would be wrong: the screen is there, something it looked up is not. ### Returning it yourself `NotFound` is an ordinary component (`io.mateu.uidl.data.NotFound`), so a view can also return one directly — or a YAML definition declare `type: NotFound` — when it wants a not-found page with its own texts or way back: ```java return NotFound.builder() .title("This booking no longer exists") .message("It was cancelled and archived on 3 October.") .backRoute("/bookings") .backLabel("See bookings") .build(); ``` ## How it looks **Vaadin** — an icon, the heading (an `<h2>`), the line and the way back, centered and drawn with the theme's Lumo tokens, so it follows light and dark: ![Not found page in the Vaadin renderer, light](/images/docs/not-found/vaadin-light.png) ![Not found page in the Vaadin renderer, dark](/images/docs/not-found/vaadin-dark.png) **Redwood** — Redwood's own idiom for this, the Spectra `oj-sp-empty-state` in its full-page layout (its illustrated background, primary and secondary text, and the way back as its navigation link), under Redwood's search icon. The page header is hidden: the empty state carries the heading, and a visually hidden `<h2>` gives it to screen readers as a heading. ![Not found page in the Redwood renderer](/images/docs/not-found/redwood.png) The way back is an in-app navigation in both — the same one a menu click makes — not a page reload. ## Notes - The Java backend only for now: the C# and Python ports still answer an error for a missing record. - Tests: `NotFoundPageSyncTest` (backend), `notFoundRenderer.test.ts` (Vaadin), the `not found` cases of the Redwood contract tests (`poc/test.mjs`), and `e2e/tests/shared/not-found.spec.ts` against every adapter. --- # Notice URL: https://mateu.io/ux-patterns/notice/ > A compact inline banner — a theme-tinted strip with a severity icon, one line of text and an optional action. **Status:** ✅ Implemented ## Intent Surface a short, glanceable notice **inside** the UI — "2 quejas pendientes" in a guest panel, "stock bajo" next to a product — as a small tinted strip that can live anywhere: inside cards, columns or forms. Smaller than a [callout card](/ux-patterns/callout-card/) (no title/CTA block) and independent of the page-level [banners](/ux-patterns/notifications/). ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Notice` component: one line of text, a small circular severity icon and an optional right-aligned action. `theme` — `info`, `success`, `warning` or `danger` — tints the strip; `icon` overrides the theme's default glyph. ```java Notice.builder() .text(guest.complaints() + " quejas pendientes") .theme("danger") .actionLabel("Revisar").actionId("review") .build() ``` ### Declarative: `@Notice` on a String field The field's **value** is the notice text — and a `null`/blank value hides the notice entirely, so the field doubles as its own visibility switch: ```java @Notice(theme = "danger", slim = true, fullWidth = true) String quejas; // set it when there is something to say; leave blank to show nothing ``` ### Options | Parameter | Effect | |---|---| | `theme` | `info` (default), `success`, `warning`, `danger` | | `icon` | overrides the theme's glyph (ℹ ✓ !) — an emoji renders at natural size, without the severity circle | | `noIcon` | suppresses the severity icon entirely | | `slim` | tight variant: no block margins, reduced padding, `line-height: normal` | | `fullWidth` | spans every form column (also stretches the wrapping field) | | `actionLabel` + `actionId` | small right-aligned action, dispatched through the standard mechanism | | `status` | right-aligned state text in the action's spot — for the in-flight/done states of the notice's action (e.g. "Enviando…", "Firmado ✓") | ### Arbitrary content The fluent `Notice` also accepts `content` — any components rendered inside the tinted strip, below the text (or on their own when there is no text): ```java Notice.builder() .text("2 quejas pendientes").theme("danger") .content(List.of(BulletedList.builder() .items(List.of("Aire acondicionado ruidoso", "Retraso en el room service")) .build())) .build() ``` ## Where it works Every web renderer (Vaadin, Redwood), React Native and the IntelliJ plugin. Also available from the C# (`new Notice("…") { Theme = "danger" }`) and Python (`fluent.Notice(text=…, theme=…)`) backends. ## Related - [Callout card](/ux-patterns/callout-card/) — the bigger sibling, with title and CTA block - [Status list](/ux-patterns/status-list/) — rows of statuses with icons and actions --- # Notification inbox URL: https://mateu.io/ux-patterns/notification-inbox/ > A bell on the app header with the unread count and a persistent notification list — events, not toasts. **Status:** ✅ Implemented ## Intent Toasts vanish; work does not. "Your export finished", "an approval is waiting", "the import had 3 errors" must survive the moment they happened and be findable later — with an unread count nudging the user. This is the **inbox** (events with read state), distinct from [push toasts](/ux-patterns/notifications/) (transient) and [task queues](/ux-patterns/task-queue/) (work items). ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Implement `NotificationsSupplier` on the `@UI` app class: ```java @UI("") public class BackofficeApp implements NotificationsSupplier { @Autowired NotificationStore notificationStore; // your inbox @Override public List<AppNotification> notifications(HttpRequest httpRequest) { // per-user inbox: the user the host framework authenticated (the same identity // @EyesOnly authorization uses) var user = httpRequest.getUserPrincipal().getName(); return notificationStore.latest(user).stream() .map(n -> new AppNotification(n.id(), n.title(), n.text(), n.route(), n.unread(), n.relativeTime())) .toList(); } @Override public void markNotificationsRead(List<String> ids, HttpRequest httpRequest) { notificationStore.markRead(httpRequest.getUserPrincipal().getName(), ids); } } ``` - The shell shows a **bell** on the header (next to the theme toggle) with the **unread count**. - The bell's panel lists the entries — title, optional text, display time (`when` is already formatted by the server: it owns locale and relative-time rules). Clicking an entry with a `route` navigates there and marks it read; **Mark all read** clears the count. - The list is fetched per request through the app-level `_notifications-list` action (the same rail as the `@AppContext` pickers' remote search), so it can be per-user and always current; `_notifications-read` (ids, or `"all"`) marks read and answers the refreshed list. - Pair with [long-running jobs](/ux-patterns/long-running-jobs/): when a background task completes, append an inbox entry so the outcome survives the toast. ## In YAML A data-authored shell feeds the bell from REST sources instead of a `NotificationsSupplier` class: `notifications: {source: …, markRead: …}` on its `type: AppShell` — fetched by the browser (or through the server when the source is `proxy: true`). See [App shell as data › Header extras](/define/yaml/app-shell/#header-extras-pickers-actions-inbox-and-search). ## Wire `AppDto.notificationsEnabled` turns the bell on; the actions answer `Data{_notifications: [{id, title, text, route, unread, when}]}` — same contract from the Java, .NET and Python servers. ## Where it works Every renderer. On **Redwood** the bell sits in the global header (badge with the unread count) and opens an `oj-popup` holding JET's `oj-list-view`; activating an entry marks it read and navigates to its route. Demo: `demo-vb-pms` (`PmsHome` implements `NotificationsSupplier`). A data-authored shell's `notifications.source` works there too: the same bell lists it (a proxied source through `_appsource`), and opening an entry or *Mark all read* calls `markRead`. ## Related - [Push notifications](/ux-patterns/notifications/) — the transient sibling - [Task queue](/ux-patterns/task-queue/) — when entries are work items with owners and states --- # Push Notifications (polling) URL: https://mateu.io/ux-patterns/notifications/ > Show live alerts and pending-task counts without a WebSocket, using trigger-based self-scheduling polls. **Status:** ✅ Implemented — `@Trigger(OnLoad + OnSuccess)`, `Hydratable`, `MicroFrontend` ## Intent Surface live information — pending tasks, system alerts, unread messages — to the user without requiring a persistent connection, and without blocking the rest of the UI. ## Problem Enterprise apps often need to notify users of asynchronous events (a workflow task assigned, an import that finished, an approval waiting). WebSockets add infrastructure complexity; SSE is fire-and-forget. A simpler approach covers most cases: a lightweight component that polls the backend on a fixed interval and updates its own display. ## Solution Combine two triggers on a component to create a self-scheduling poll loop: 1. `@Trigger(type = OnLoad, actionId = "X", timeoutMillis = N)` — fires action `X` N ms after the component loads. 2. `@Trigger(type = OnSuccess, actionId = "X", calledActionId = "X", timeoutMillis = N)` — fires action `X` again N ms after each successful completion of `X`. The action returns `new State(this)`, which pushes the updated component state to the frontend. `Hydratable.hydrate()` runs before each render to refresh data from the backend. --- ## Structure ``` Shell header └── MicroFrontend (/_forms/my-tasks) └── TasksWidget @Trigger OnLoad ──────────────────────────────────┐ @Trigger OnSuccess (calledActionId = refreshTasks) │ ↓ (after 5 s) │ refreshTasks() → State(this) │ hydrate() ← reads DB / service │ component() ← renders updated content │ └──────────────────────────────────────────────┘ ``` --- ## Implementation ### 1. The notification widget :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @UI(value = "/_forms/my-tasks") @Title("") @Service @RequiredArgsConstructor @Trigger(type = TriggerType.OnLoad, actionId = "refreshTasks", timeoutMillis = 5000) @Trigger(type = TriggerType.OnSuccess, actionId = "refreshTasks", calledActionId = "refreshTasks", timeoutMillis = 5000) @Action(id = "refreshTasks") public class TasksWidget implements Hydratable, ComponentTreeSupplier { final TaskRepository repository; String content; // Called before rendering — refresh data from the backend @Override public void hydrate(HttpRequest httpRequest) { // the caller as the host framework authenticated it (Mateu never reads the token itself) var user = IdentityResolver.resolve(httpRequest).name(); long pending = repository.countPendingFor(user == null ? "" : user); if (pending > 0) { content = "<a href=\"#\" onclick=\"" + navScript() + "\" " + "style=\"animation: fade 2s ease-in-out infinite alternate;\">" + "You have " + pending + " task(s)!" + "</a>" + "<style>@keyframes fade{from{opacity:1}to{opacity:0}}</style>"; } else { content = "<a href=\"#\" onclick=\"" + navScript() + "\">No pending tasks</a>"; } } // Returns updated state to the frontend — triggers re-render Object refreshTasks() { return new State(this); } @Override public Component component(HttpRequest httpRequest) { return Text.builder().text("${state.content}").build(); } private String navScript() { return "event.preventDefault(); this.dispatchEvent(new CustomEvent(" + "'navigation-requested',{detail:{" + "route:'/forms/tasks',consumedRoute:''," + "baseUrl:'/_forms',serverSideType:'io.example.FormsHome'" + "},bubbles:true,composed:true}))"; } } ``` ### 2. Embedding the widget in the shell Embed the widget as a `MicroFrontend` inside the shell's `widgets()`. The widget lives in a separate service — the shell just points to its URL. ```java @UI("") public class ShellHome implements WidgetSupplier { @Override public List<Component> widgets(HttpRequest httpRequest) { return List.of( HorizontalLayout.builder() .content(List.of( // ... other header widgets (user menu, etc.) go in this list too MicroFrontend.builder() .baseUrl("/_forms") .route("/my-tasks") .build() )) .style("align-items: flex-end;") .build() ); } } ``` --- ## How the poll loop works | Step | What happens | |---|---| | Page loads | `OnLoad` trigger fires after `timeoutMillis` ms | | `refreshTasks()` runs | `hydrate()` reads the DB; action returns `State(this)` | | Frontend receives new state | Component re-renders with updated content | | `OnSuccess` trigger fires | After `timeoutMillis` ms, calls `refreshTasks()` again | | Loop continues indefinitely | Until the user navigates away or the component is unmounted | The interval is set independently on each trigger, so you can load immediately but poll less frequently: ```java @Trigger(type = TriggerType.OnLoad, actionId = "poll", timeoutMillis = 0) // immediate @Trigger(type = TriggerType.OnSuccess, actionId = "poll", calledActionId = "poll", timeoutMillis = 10_000) // every 10 s ``` --- ## Key interfaces and types | Type | Role | |---|---| | `Hydratable` | `hydrate(HttpRequest)` is called before each render — use it to populate fields from the backend | | `State(this)` | Return value from an action — pushes the component's current field values to the frontend | | `MicroFrontend` | Embeds a remote `@UI` component inside the host shell | | `WidgetSupplier` | Interface on the shell class that injects components into the header widget area | --- ## Variants - **Badge count** — render an integer and style it as a pill badge. - **System alert banner** — render a full-width coloured banner when a critical condition is detected. - **Cross-service** — the widget `@UI` lives in a different microservice from the shell; the shell embeds it via `MicroFrontend` pointing to that service's base URL. - **Auth-aware** — resolve the current user in `hydrate()` to filter tasks by it (see the example above: `IdentityResolver.resolve(httpRequest).name()` is the identity the host framework authenticated — see [security](/java-user-manual/advanced/security/#how-authorization-works)). --- ## Principles served - **Preserve context** — notifications appear in-place; the user is not redirected - **Progressive complexity** — the widget is invisible when there is nothing to report - **Workflow over screens** — one click takes the user directly to the pending-tasks screen --- # Offer card URL: https://mateu.io/ux-patterns/offer-card/ > A current-vs-upgrade offer card — image, features, price delta and a single call to action. **Status:** ✅ Implemented ## Intent Present an upsell the way a salesperson would — the upgrade next to what the customer already has, with a photo, the differentiating features and the price *delta* — so accepting it is one click at the moment of highest relevance (e.g. room assignment during check-in). ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `OfferCard` component: an optional `image` header (16:9 cover, skipped when absent), a floating `tag` chip, `title` + `subtitle`, `features` rendered as outline chips, and a footer. A non-current card shows a full-width primary button (`actionLabel`, with `priceLabel` right-aligned inside) and an accent border; the current/assigned variant (`current(true)`) shows a muted `currentLabel` instead of any CTA. ```java @Section("Upgrade") Component upgrade = OfferCard.builder() .tag("UPGRADE DISPONIBLE") .title("Master Oceanfront Suite").subtitle("Planta 14 · Primera línea") .image("https://example.com/suite.jpg") .features(List.of("68 m²", "Vista mar frontal", "Terraza + jacuzzi", "Sofá lounge")) .priceLabel("+ € 65 / noche") .actionLabel("Mejorar a esta habitación").actionId("upgrade") .build(); Component assigned = OfferCard.builder() .tag("HABITACIÓN ASIGNADA") .title("Ocean Suite").subtitle("Planta 12") .features(List.of("45 m²", "Vista mar lateral", "Balcón")) .current(true).currentLabel("✓ Incluida en tu reserva") .build(); ``` ![Offer card](/images/docs/offer-card/offer-card.png) The CTA dispatches the standard `action-requested` event with the card's `actionId` and **no parameters** — one card, one offer, one action. Current cards dispatch nothing. ### Toggle offers When the offer can be added *and removed* (an optional upgrade), drive the CTA as a toggle from the server state: set `added(boolean)` and `addedLabel("✓ Upgrade añadido")` when building the card — while `added` is true the button turns success green and shows `addedLabel` (the `priceLabel` stays right-aligned); clicking dispatches the same `actionId` again, so the action just flips its flag and re-renders: ```java public Object handleAction(String actionId, HttpRequest httpRequest) { if ("upgrade".equals(actionId)) { habitacion.setUpgradeAnadido(!habitacion.isUpgradeAnadido()); return this; // the card re-renders with the flipped added state } return null; } ``` ## When to use it Use an `OfferCard` for a **single, contextual offer** — typically a current-vs-upgrade pair side by side. To compare several plans/tiers in columns use a [Pricing table](/ux-patterns/pricing-table/); for many small priced extras with a running total use an [Add-on picker](/ux-patterns/addon-picker/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/offer-card-demo`. --- # Concurrent edit conflicts URL: https://mateu.io/ux-patterns/optimistic-locking/ > @Version optimistic locking — the second writer gets a conflict dialog instead of silently losing the first writer's changes. **Status:** ✅ Implemented ## Intent Two users open the same record; both edit; both save. Without protection the second save silently erases the first — the classic *lost update*. Enterprise apps need the second writer to **know**, and to choose: see the other changes, or overwrite them deliberately. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Add a `@Version` field (an `int` or `long`) to the entity: ```java public class Article implements Identifiable { String id; String name; @Version long version; // never an input on the edit/creation form; it still travels in state @Override public String id() { return id; } } ``` - Every successful save **bumps** the version automatically. - A save carrying a version **older** than the stored one (someone else saved in between) is rejected: nothing is persisted and the user gets the **conflict dialog** — *"Modified by another user"* — with two choices: - **Reload** — discard my changes and show the record with theirs (the routed editor goes to the record's view; the edit drawer stays open, refreshed with the stored values). - **Overwrite** — my version wins, explicitly. The save is re-dispatched with `_forceOverwrite`; the version keeps moving forward (the stale number is never resurrected). Either way the dialog closes with the answer. Its texts are English and go through your `Translator` like every other Mateu text: translate *"Modified by another user"*, *"Reload"*, *"Overwrite"* and the two messages (*"This record changed while you were editing it…"*, *"This row changed…"*) to localise it. - The version field is never shown as an input on the edit or creation form (a user could otherwise type their way past the check); a read-only view still shows it. - Works out of the box on `AutoCrud` editors **and** inline row editing (`@InlineEditing`), where the dialog re-sends the same edited row on overwrite. - Entities without a `@Version` field are untouched — the feature is fully opt-in. ## Database-backed repositories The check compares against `store().findById(...)` at save time. A **store-managed** version — a field annotated with JPA's `@jakarta.persistence.Version` (or Spring Data's `@org.springframework.data.annotation.Version`) — takes part in that check like Mateu's own `@Version`, so a stale save gets the same dialog and *Overwrite* adopts the stored version; but Mateu does **not** bump it, because the persistence provider increments it itself. For a race the check cannot see, throw `OptimisticLock.StaleEditException` from `save` (e.g. translate Spring's `OptimisticLockingFailureException` in your store). ## Related - [Autosave](/ux-patterns/autosave/) — fewer stale windows by saving continuously - [Audit history](/reference/key-annotations/) — `Auditable` records who changed what --- # Org chart URL: https://mateu.io/ux-patterns/org-chart/ > Show a hierarchy top-down — an org chart, a category tree, a reporting line. **Status:** ✅ Implemented ## Intent Show a hierarchy — who reports to whom, a category tree, a decision tree — as a classic top-down chart, so the structure and depth read at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `OrgChart` component: a single `root` `OrgNode` whose `children` fan out below it, connected by lines. Each node has a title, optional subtitle, an `avatar` (emoji or image URL) and accent `color`. A node with an `actionId` is clickable. ```java @Section("Leadership") Component org = OrgChart.builder() .root(OrgNode.builder().title("Ada Lovelace").subtitle("CEO").avatar("👑").color("#1a73e8") .actionId("openPerson") .children(List.of( OrgNode.builder().title("Alan Turing").subtitle("CTO").avatar("💻") .children(List.of( OrgNode.builder().title("Grace Hopper").subtitle("VP Eng").build())) .build(), OrgNode.builder().title("Katherine J.").subtitle("CFO").avatar("📊").build())) .build()) .build(); ``` ![Company org chart](/images/docs/org-chart/company-org.png) The renderer is dependency-free (CSS-connector tree), themes through the standard CSS variables, works in dark mode and scrolls horizontally when wide. On mobile (React Native) and in the IntelliJ plugin the same tree renders **indented** — the natural narrow-viewport adaptation. ## When to use it Use an `OrgChart` for **top-down hierarchies** you want to see whole. For a large, navigable tree (file explorer, deep taxonomy) use a `GridLayout.tree` listing or a tree select instead. Demo: `/orgchart-demo`. --- # Page templates URL: https://mateu.io/ux-patterns/page-templates/ > The full-page templates enterprise design systems standardize — and the Mateu archetype or pattern that builds each one from your UI model. Enterprise design systems (Oracle Redwood's RDS toolkit is the canonical example) don't stop at components — they standardize **full-page templates**: the record overview, the collection with a detail pane, the guided process, the create-and-edit drawer. Mateu covers these templates from the UI model: you extend an archetype or set a flag, and the page comes out with the template's anatomy on every renderer that paints its components (see the Redwood column). This page is the map. Each row names the template (RDS naming), the Mateu piece that builds it, and where to see it running. **The normal way to build a UI starts here**: list the screens your app needs, decide the [page type](/ux/page-types/) and the template for each one, then declare the data — choosing the template is your call per screen (Mateu only composes it for you in two fully-derivable cases; see [Choosing a page template](/ux-patterns/choosing-a-page-template/), the decision guide). | Template | Mateu piece | Demo route | Guide | Redwood | |---|---|---|---|---| | **Smart Filter and Search** | Every CRUD/`Listing` — the smart search bar with typed filters, chips and saved views is the default listing UX | `/products` | [Filters & listing](/ux-patterns/filters-and-listing/) | ✅ | | **Smart Search page** | `SmartSearchPage<Filters, Row>` archetype — a standalone, search-first page: intro line + smart search bar with typed facets + results; starts empty | `/smart-search-demo` | [Smart search](/ux-patterns/smart-search/) | ✅ | | **To-do list** | `TodoList<Row>` archetype — pending work as counted buckets of actionable cards; clicking a task acts on it | `/todo-list-demo` | [To-do list](/ux-patterns/to-do-list/) | ✅ | | **Create and Edit — Simple** | `AutoCrud<T>` — routed `/new` and `/{id}/edit` forms with validation, optimistic locking and dirty guard | `/products` | [Create and edit](/ux-patterns/create-and-edit/) | ✅ | | **Create and Edit — Advanced** | a sectioned transactional form with a canonical header (save/cancel, `@Timestamp`, `@KPI` facts, peer-nav) and either `@Toc` (section index) or `@Aside` (detail slot) | — | [Advanced create & edit](/ux-patterns/advanced-create-and-edit/) | 🟡 no `@Toc` index | | **Create and Edit — Drawer** | `editInDrawer()` on the crud — the form slides over the listing, which never unmounts | `/drawer-crud-demo` | [Drawer](/ux-patterns/drawer/#crud-editing-in-a-drawer-editindrawer) | ✅ | | **Waterfall detail** | Composition — a `VerticalLayout` of `EntityHeader` + full-width `Card`/property-list panels telling the record top-to-bottom | — | [Waterfall detail](/ux-patterns/waterfall-detail/) | ✅ | | **Step-by-step** | `Wizard` + `@WizardProgress(STEPS)` — the classic numbered-step stepper with done/current/upcoming states | `/branching-wizard` | [Wizard](/ux-patterns/wizard/) | ✅ `oj-train` | | **Collection Detail** | `CollectionDetail<Row>` archetype — searchable card list + in-place detail pane | `/collection-detail-demo` | [Collection detail](/ux-patterns/collection-detail/) | ✅ | | **General Overview** | `GeneralOverview<Row>` archetype — record context switcher + `EntityHeader` metadata strip over property cards | `/general-overview-demo` | [General overview](/ux-patterns/general-overview/) | ✅ card contents render as atoms (a `Grid` is an `oj-table`) | | **Guided Process** | `Wizard` + `@WizardProgress(RAIL)` — step form with the sticky lateral rail (`current \| total` counter over the vertical step list) | `/branching-wizard` | [Wizard](/ux-patterns/wizard/) | ✅ | | **Item Overview** | `ItemOverview` archetype — sticky key-info panel + tabbed detail | `/product-overview` | [Item overview](/ux-patterns/item-overview/) | ✅ key panel and tabs render their components (Markdown, charts, lists…) | | **Foldout Layout** | `Foldout` archetype — fixed overview + lateral fold-out panels | `/foldout-demo` | [Foldout](/ux-patterns/foldout/) | ✅ `oj-sp-foldout-layout` | | **Dashboard** | `Dashboard` archetype — KPI scoreboard band + responsive tile grid | `/dashboard-demo` | [Dashboard](/ux-patterns/dashboard/) | ✅ KPI band + `oj-chart` tiles | | **Welcome Page** | `Welcome` archetype — hero with CTAs + highlight tiles | `/welcome-demo` | [Welcome page](/ux-patterns/welcome-page/) | ✅ | | **Empty States** | `EmptyState` component — used by every listing and archetype automatically | `/empty-skeleton-demo` | [Empty states & skeletons](/ux-patterns/empty-states-and-skeletons/) | ✅ (`Skeleton` —) | | **Data Management** (grid ⇄ Gantt) | `DataManagement` archetype — the same data as a grid and a Gantt with a toolbar switcher (full-width). Dense editable grids use `@InlineEditing` + `@Compact` | `/data-management-demo` | [Data management](/ux-patterns/data-management/) | ✅ grid as `oj-table`, Gantt as `oj-gantt` | | **Gantt page** | `GanttPage` archetype — edge-to-edge Gantt canvas + docked detail; clicking a bar opens the task in a drawer | `/gantt-page-demo` | [Gantt](/ux-patterns/gantt/#gantt-page-template-ganttpage-archetype) | ✅ `oj-gantt`; a bar click opens the task drawer | | **Calendar** | `CalendarPage` archetype — the full page: calendar toolbar (‹/Today/›, optional *+ Create*) over the calendar, per-month event fetching, event click actions, month/week/day/list views, per-date labels and clickable dates | `/calendar-demo` | [Calendar](/ux-patterns/calendar/) | ✅ | Three notes on how to read the table: - **Templates are backend-side.** An archetype composes existing wire components, so it renders wherever those components render — on Vaadin and the native renderers (React Native, IntelliJ) without renderer work. **Redwood is the exception to watch**: it paints a curated set of components with Oracle's own, and shows a visible *Unsupported component* placeholder for the ones it has no view for — the last column says what each template looks like there, and the [Redwood component coverage](/reference/parity/#redwood-component-coverage) table (checked in CI) says why. Styling follows each design system's tokens. - **Page width is a template parameter.** `@PageWidth(FIXED | FULL_WIDTH | EDGE_TO_EDGE)` (or the `PageWidthSupplier` hook — `Foldout` declares edge-to-edge) decides how the content column is sized: capped and centered, fluid with side margins, or touching the viewport edges. When neither is set, the renderer infers it from the content (full-bleed canvases → edge-to-edge, dense datagrids → full width, anything else → fixed). On the Vaadin shell all three modes render: *fixed* caps the content column at 1408 px centered, *full width* is fluid, and *edge to edge* drops the shell gutters for the content while the page header keeps its own side padding (so the title never touches the viewport edge). - **A leading `EntityHeader` becomes the page header.** When a page's content starts with an `EntityHeader` (the guest/record banner), the renderer hoists it into the canonical page header: its title becomes the page title with the badges beside it, its subtitle the page subtitle, and its facts + metric render as a row of label/value pairs under the title — the banner is not repeated in the body. This is the Redwood record-header anatomy without any extra annotation: compose the `EntityHeader` as the first component and the header comes out integrated. Applies to top-level pages only; embedded islands keep their banner inline. - **Secondary header actions collapse into a "…" menu.** Toolbar buttons marked primary stay visible in the page header; when a page declares two or more secondary actions they collapse into an overflow menu (the Redwood header grammar), keeping the header to one primary action plus "…". A single secondary action stays inline. - **The page type is inferred from the ModelView.** Every page carries a coarse `pageType` on the wire — `landing` (Welcome, HeroSearch), `collection` (listings, search pages, CRUDs, to-do lists, calendars, collection detail), `detail` (overviews, foldout, master-detail), `form` (plain reflected forms), `process` (wizards), `dashboard` (archetype, or any ModelView with `MetricCard` fields). Archetypes declare theirs through the mapping; declare it explicitly with `@PageTemplate(PageType.X)` — or, on a YAML page, with a top-level `pageType: landing` key ([YAML pages](/define/yaml/pages/#page-type--pagetype)); declared, either wins over inference. The type anchors the width default (form/process/landing are always capped; collection/detail/dashboard defer to the content inference) and is stamped as `data-page-type` on the rendered page host as a stylesheet hook. - **Peer navigation.** A detail/overview page can implement `PeerNavigationSupplier` to add the previous/next-object arrows to the header (the Redwood "next/previous object" element): return a `PeerNav(prevLabel, prevRoute, nextLabel, nextRoute)` for the current record — a `null` route disables that side. Ported to .NET (`IPeerNavigationSupplier`) and Python (`PeerNavigationSupplier`). Demo: `/peer-nav-demo`. ![Peer navigation: the ‹ › arrows in the page header step to the previous/next record](/images/docs/page-templates/peer-navigation.png) - **Header overline and title placeholder.** Two small text elements of the Redwood canonical header. `@Overline("Requisitions")` puts a quiet line **above** the title — a category, a parent context, a step marker. `@TitlePlaceholder("New booking…")` supplies what the header shows **while the title is still empty** (the create-mode affordance); it is a placeholder, not a default, so it disappears the moment a title exists. Both follow the house rule for page metadata: implement `OverlineSupplier` / `TitlePlaceholderSupplier` when the text depends on runtime state, and the supplier wins over the annotation. They travel on the wire as `PageDto.overline` / `PageDto.titlePlaceholder`. - **Header timestamp.** Mark a field with `@Timestamp("Last updated")` to show a "last updated" line in the header (the Redwood timestamp element); the field's value renders as text and the field is dropped from the form body. Header key/value facts come from `@KPI` fields the same way. Ported to .NET (`[Timestamp]`) and Python (`Timestamp()`). - **On Redwood** these elements use the `oj-sp` page header's own: the peer arrows are its previous/next item actions, the first header badge is its status badge (more badges follow the subtitle), and a timestamp whose value is a date (`2026-10-12T10:42`, label empty or "Last updated") is its timestamp element, which writes its own translated "Last updated …"; any other timestamp text ends the subtitle line. The header has no overline or placeholder element, so the renderer draws the overline above the title and dims the placeholder title. Demo: `demo-vb` `/header-extras` (Java) and `/yaml-header` (the same page in YAML). - **Backend parity.** Everything on this page also works on the .NET and Python backends — see the [parity matrix](/reference/parity/) for the per-feature detail. - **Composition beats templates.** When no template fits, the same pieces compose freely: `HeroSection`, `EntityHeader`, `TaskQueue`, `Card`, property-list sections, zones and the fluent `FormField` are the vocabulary the archetypes themselves are written in. - **Uniform content-page slot grammar.** The templates with a *main + contextual aside* shape (`ItemOverview` — key-info panel + tabs; `CollectionDetail` — searchable list + detail pane) compose a single `ResponsiveGrid` **template**: named areas (`gridTemplateAreas`, e.g. `"keyinfo tabs"`), the content dropped into them as `Slotted` children, `stickyAreas` for a pinned region and `stackBelow` for the width under which the areas stack — instead of each reinventing a bespoke layout. The aside sits beside the main region on wide viewports and stacks under it when narrow. It is a wire component like `FoldoutLayout`, so you can also compose it directly in a custom view; ported to .NET and Python. (The older `ContentLayout` with `main`/`aside`/`footer` regions is deprecated: no archetype produces it any more.) - **`@Aside` — content-page from a plain form.** The minimal way to get the content-page grammar without composing anything: on an ordinary reflected form, mark one component-holder field `@Aside` (`.NET` `[Aside]`, Python `Aside()`). That field is pulled out of the form body and placed in the aside area; the rest of the form becomes the main area of the same kind of grid template (`position`/`width`/`sticky` come from the annotation). You keep declaring data as usual and just point at the one supporting panel that belongs to the side. ## The header in YAML Every header element on this page — overline, title placeholder, timestamp, badges, KPIs, peer navigation, the record switcher, banners and page FABs — is authorable on a YAML page's `type: Form` too, with the same wire fields. See [YAML pages › Page header](/define/yaml/pages/#page-header--type-form). ## Record and context switcher :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The Redwood header's `selectObject` / `selectContext` element, available on **any** page with a header — not only inside `GeneralOverview`. Implement `RecordSwitcherSupplier` (the sibling of `PeerNavigationSupplier`: peer navigation steps to the previous/next record, the switcher jumps to any of them): ```java @UI("/customer") public class CustomerPage implements RecordSwitcherSupplier { public String customer = "c1"; @Override public RecordSwitcher switcher(HttpRequest rq) { return RecordSwitcher.builder() .options(customers.stream().map(c -> new Option(c.id(), c.name(), c.city())).toList()) .value(customer) .type(SwitcherType.object) // or context: what the page is evaluated in .label("Customer") .searchable(true) // type-ahead over label + description .build(); } @Override public Object switchTo(String value, HttpRequest rq) { customer = value; // point the page at the new record… return this; // …and re-render in place (or return a URI to navigate) } } ``` It travels as `PageDto.switcher`; a pick runs the page's `_switchRecord` action with the value in `_record`, which calls `switchTo`. Vaadin draws a native select (a filtering combobox when `searchable`) beside the title; Redwood uses the oj-sp header's own data switcher (with `switcherSearch`); React Native a pill opening a bottom sheet; IntelliJ a combo box with speed search. ![The header switcher, searching](/images/docs/page-templates/record-switcher.png) ## Announcements The Redwood `announcement` slot — what a screen-reader user should hear when nothing on screen takes focus — is a command any action can return: `UICommand.announce("3 rows imported")`, or `UICommand.announceAssertive(text)` for errors (it interrupts). Nothing is drawn; each renderer pushes the text through its live region (web), `AccessibilityInfo` (React Native) or the IDE's announcer (IntelliJ). The CRUD edit drawer already announces a failed save. ## Display options: one tri-state grammar Redwood switches a template's built-in affordances through `displayOptions`, each `on`, `off` or `disabled`. Mateu's equivalent is the shared `Toggle` enum (`on` · `off` · `disabled` = shown but inert — the state permissions need) grouped in one display record per archetype, returned by an overridable `display()`: | Archetype | Record | Toggles | |---|---|---| | `Wizard` | `WizardDisplay` | `saveDraft`, `saveAndClose`, `skip` | | `Crud` / `AutoCrud` | `CrudDisplay` | `create`, `delete`, `saveAndNext`, `errorBanner` | | `GeneralOverview` | `GeneralOverviewDisplay` | `info`, `promoteInfoSlot` | Toggles are consumed on the server while composing — a `disabled` affordance travels as a disabled button and is refused if forced, an `off` one does not travel — so no renderer needs to know about them. The existing gates (`canCreate`, `@NotDeletable`…) still decide whether an affordance exists; the display record decides how it shows. Only the archetypes with affordances worth switching have a record: inventing toggles for the others would be surface without behaviour. ## Section affordances The Redwood `section` template's edit / add / view-more actions, on any `@Section`: ```java @Section(value = "Guests", addAction = "addGuest", editAction = "editGuests") public String leadGuest; @Section(value = "Payments", viewMoreAction = "allPayments") public String lastPayment; ``` Each attribute names an action method of the form: *Add* and *Edit* render as small tertiary buttons on the section's title row, *View more* as a link under its content. They are ordinary buttons composed on the server, so every renderer draws them. ## Coverage of the header and cross-template pieces | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Record / context switcher | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Announcements | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Display records (`Toggle`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Section affordances | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Peer navigation, overline, title placeholder, timestamp | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | --- # Partial Forms URL: https://mateu.io/ux-patterns/partial-forms/ > Divide a complex form into independent, collapsible sections each with its own toolbar actions. **Status:** ✅ Implemented — `@FoldedLayout`, `@Section`, nested records/classes, `@Toolbar` on subforms ## Intent Allow users to work on one part of a complex entity at a time, without being forced to save (or scroll through) the entire form at once. ## Problem A customer record, a product sheet, or a booking with dozens of fields is overwhelming as a single flat form. Forcing a global Save on the whole page means: - The user cannot partially save one section while leaving another incomplete. - The page becomes a scroll prison — everything visible at once, nothing prioritised. - Section-specific actions (e.g. "Test connection" on a credentials section) don't fit naturally alongside a global Save. ## Solution Use `@Section` to split fields into groups (and `@FoldedLayout` on the page class to lay those groups side by side). Define each logical group as a **nested record or class** (a subform field). Methods annotated with `@Toolbar` or `@Button` inside those nested types become actions scoped to that section only. ``` Page [@FoldedLayout] ├── @Section "General" → plain fields + global @Toolbar save ├── @Section "Address" → Subform1 field │ └── Subform1.test1() [@Toolbar] ← section-scoped button └── @Section "Preferences" → Subform2 field └── Subform2.test2() [@Button, shortcut ctrl+f1] ← inline button ``` --- ## Example ### Page class :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @FoldedLayout @Action(shortcut = "ctrl+f2", id = "save") @ConfirmOnNavigationIfDirty public class Page3 { @Section("sf0") // plain fields — belong to the global form String name; int age; @Section("sf2") // section whose content is a subform Subform1 subform1; @Section("sf1") Subform2 subform2; @Toolbar // global save — operates on the whole page Object save() { return List.of( Message.builder().variant(NotificationVariant.success) .text("Saved " + this).build(), UICommand.markAsClean() ); } } ``` ```yaml # src/main/resources/specs/ui/routes.yaml type: Routes routes: - route: home2 children: - route: page3 viewModel: com.example.Page3 ``` ### Subform with a toolbar action ```java public record Subform1(String address, String city) { @Toolbar // button appears in the "sf2" section toolbar Object test1() { return Message.builder().text("test1 on " + this).build(); } } ``` ### Subform with an inline button and a shortcut ```java public record Subform2( @Stereotype(FieldStereotype.radio) Sex sex, Religion religion ) { @Button @Action(shortcut = "ctrl+f1", confirmationRequired = true) Object test2() { return Message.builder().text("test2 on " + this).build(); } } ``` --- ## How it works | Element | Role | |---|---| | `@FoldedLayout` | Lays the `@Section` cards side by side, one column each, instead of stacking them | | `@Section("name")` | Starts a new collapsible group; fields below it belong to this group until the next `@Section` | | Nested record/class field | Becomes the subform rendered inside the section | | `@Toolbar` on a subform method | Adds a button to that section's own toolbar, scoped to the subform's data | | `@Button` on a subform method | Adds an inline button inside the section fields | | `@Toolbar` on the page class | Global toolbar action that can access all sections | | `@ConfirmOnNavigationIfDirty` | Warns the user before navigating away with unsaved changes | --- ## Structure ``` ┌─ Page3 ──────────────────────────────────────────────────────┐ │ [Save ⌘F2] ← global toolbar │ ├─ sf0 ▼ ──────────────────────────────────────────────────────┤ │ Name [_________] Age [___] │ ├─ sf2 ▼ ──────────────────────────────────────────────────────┤ │ [test1] ← Subform1 toolbar │ │ Address [_________] City [_____] │ ├─ sf1 ▼ ──────────────────────────────────────────────────────┤ │ Sex ● Male ○ Female ← radio (Subform2) │ │ Religion [Catholic ▼] │ │ [test2 ⌃F1] ← @Button inline │ └──────────────────────────────────────────────────────────────┘ ``` --- ## When to use - **Complex entities** with 15+ fields naturally grouped into independent concerns (personal data, contact, billing, preferences, …). - **Section-specific actions** that only make sense for that group (e.g. "Validate address", "Test credentials", "Preview"). - **Progressive disclosure** — show the most important section open by default, collapse the rest. - **Independent save per section** — each subform's `@Toolbar` action can persist only its own slice of data. ## When not to use - Short forms (< 8 fields) — the overhead of collapsible panels is not worth it. - Wizard flows where sections have strict ordering — use [`@WizardCompletionAction`](/ux-patterns/wizard/) instead. --- ## Principles served - **Progressive complexity** — advanced sections are collapsed until needed - **Workflow over screens** — section-scoped actions avoid a round-trip to a dedicated sub-page - **Recoverability** — `@ConfirmOnNavigationIfDirty` prevents accidental data loss --- # Payment picker URL: https://mateu.io/ux-patterns/payment-picker/ > Payment method selection with a context chip and a confirm call to action. **Status:** ✅ Implemented ## Intent Close a payment in one row: pick the method (card, cash, points…), see the relevant context (the preauthorized amount, the balance) and confirm — without a detour through a separate payment screen. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `PaymentPicker` component: an `actionId`, a list of `PaymentMethod`s rendered as segmented outline buttons, a `selected` method id seeding the client-side selection, an optional context chip (`contextLabel` over `contextValue`, success-tinted) and a primary `confirmLabel` button. ```java @Section("Cobro") Component payment = PaymentPicker.builder() .actionId("confirmPayment") .methods(List.of( PaymentMethod.builder().id("card").label("Tarjeta").build(), PaymentMethod.builder().id("cash").label("Efectivo").build(), PaymentMethod.builder().id("points").label("Puntos").build())) .selected("card") .contextLabel("PREAUTORIZADO").contextValue("€ 1.800,00") .confirmLabel("Confirmar — € 1.710,50") .build(); ``` ![Payment picker](/images/docs/payment-picker/payment-picker.png) Switching methods is client-side state; only the confirm button talks to the server — it dispatches the standard `action-requested` event with the component's `actionId` and parameters `{ "_method": selectedId }`, so the `@Action` method reads which method was chosen. ## When to use it Use a `PaymentPicker` as the **final step of a monetary flow**, directly under the [Ledger](/ux-patterns/ledger/) it settles — check-out, POS charge, deposit collection. If charges are still accruing, show the balance with a [Meter](/ux-patterns/meter/) instead of charging yet. See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/payment-picker-demo`. --- # Planning board / tape chart URL: https://mateu.io/ux-patterns/planning-board/ > Assign date-range blocks to resources on a rooms-by-days grid, with drag-to-move. **Status:** ✅ Implemented ## Intent Show and re-plan date-range assignments over a set of resources — the rooms × days grid every hotel, rental or staffing back-office needs. Rows are resources (rooms, vehicles, employees), columns are days, and each booking/assignment is a colored block spanning its dates. Overbooking gaps, free ranges and collisions are visible at a glance, and a block can be dragged to another room or day. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `PlanningBoard` component: a list of `PlanningResource` rows (with an optional `group` swimlane caption, e.g. the floor or the room type), a list of `PlanningBlock`s (each pointing at its resource by id and spanning `start` to `end`, inclusive), and the visible window (`from`/`to`; when omitted, the window is derived from the blocks). ```java @Section("Tape chart") Callable<Component> board = () -> PlanningBoard.builder() .from(LocalDate.now().minusDays(3)) .to(LocalDate.now().plusDays(17)) .resources(List.of( PlanningResource.builder().id("101").label("Room 101 · Double").group("Floor 1").build(), PlanningResource.builder().id("102").label("Room 102 · Double").group("Floor 1").build(), PlanningResource.builder().id("201").label("Room 201 · Suite").group("Floor 2").build())) .blocks(bookings.stream() .map(b -> PlanningBlock.builder() .id(b.id()).resourceId(b.room()) .start(b.start()).end(b.end()) .label(b.guest()).color(b.color()).status(b.status()) .build()) .toList()) .moveActionId("moveBooking") .selectActionId("openBooking") .build(); ``` The renderer is dependency-free (plain CSS grid), themes through the standard CSS variables, and works in dark mode. The resource label column stays pinned while the days scroll horizontally; weekends are tinted, today is marked, and hovering a block shows its label, dates and status. ![A planning board: rooms × days, stays as bars](/images/docs/planning-board/tape-chart.png) ## The action contracts Both interactions are opt-in — a board without action ids is read-only. **Select** (`selectActionId`): clicking a block runs the action with the block's id: ``` parameters: { _blockId: "b3" } ``` **Move** (`moveActionId`): blocks become draggable (a dashed ghost previews the target row/days while dragging; `Escape` cancels, and dropping a block back where it started is a no-op). Dropping runs the action with the target resource and the new dates — same duration, ISO-8601: ``` parameters: { _blockId: "b3", _resourceId: "202", _start: "2026-08-05", _end: "2026-08-11" } ``` The handler is a plain `@Action` method: read the parameters, mutate the model, and re-render: ```java @Action Object moveBooking(HttpRequest httpRequest) { var params = httpRequest.runActionRq().parameters(); var booking = findBooking(String.valueOf(params.get("_blockId"))); booking.moveTo( String.valueOf(params.get("_resourceId")), LocalDate.parse(String.valueOf(params.get("_start"))), LocalDate.parse(String.valueOf(params.get("_end")))); return List.of(new State(this), new Message(booking.guest() + " moved")); } @Action Object openBooking(HttpRequest httpRequest) { var booking = findBooking(String.valueOf( httpRequest.runActionRq().parameters().get("_blockId"))); return new Message(booking.guest() + " · " + booking.start() + " → " + booking.end()); } ``` Reject an invalid move by returning a `Message` without changing the data — the board re-renders from the unchanged model, snapping the block back. ## When to use it Use a planning board when the question is "**who/what is where, when**" and the answer must be re-arrangeable in place: room planning, fleet assignment, shift/staff allocation, equipment rental. For monitoring the *progress* of scheduled work (one row per task, not per resource), use the [Gantt](/ux-patterns/gantt/) instead; for status-lane workflows use the Kanban. Demo: `/planning-demo` in `demo-admin-panel` (`RoomPlanning.java`) — 6 rooms grouped by floor over 3 weeks; drag a booking to another room/day and the demo data updates. --- # Pricing table URL: https://mateu.io/ux-patterns/pricing-table/ > Compare plans side by side — a pricing page, a plan chooser, a feature matrix. **Status:** ✅ Implemented ## Intent Let a user compare options side by side and pick one — a SaaS pricing page, an in-app plan chooser, an upgrade prompt — so the differences and the recommended choice read at a glance. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `PricingTable` component: one `PricingPlan` per column, each with a name, a price and period, a list of feature lines and a call-to-action (`ctaLabel` + `actionId`). Mark one plan `featured` to lift and ring it as the recommended option; its CTA runs the `@Action` named by its `actionId`. ```java @Section("Choose a plan") Component pricing = PricingTable.builder() .plans(List.of( PricingPlan.builder().name("Starter").price("0€").period("/mo") .features(List.of("1 project", "Community support")) .ctaLabel("Start free").actionId("choosePlan").build(), PricingPlan.builder().name("Pro").price("29€").period("/mo").featured(true) .features(List.of("Unlimited projects", "Priority support")) .ctaLabel("Go Pro").actionId("choosePlan").build(), PricingPlan.builder().name("Enterprise").price("Custom") .features(List.of("SSO & SAML", "99.9% SLA")) .ctaLabel("Contact sales").actionId("contactSales").build())) .build(); ``` The `actionId` method receives the click; read which plan was chosen from the button context, or give each plan a distinct `actionId`. ![Pricing plans](/images/docs/pricing-table/plans.png) The renderer is dependency-free, themes through the standard CSS variables, and works in dark mode. Cards wrap onto multiple rows on narrow viewports; features render as a check list; the featured plan is highlighted with a "Recommended" badge and an accent CTA. ## When to use it Use a `PricingTable` for **side-by-side plan comparison with a choice to make**. For a plain feature grid without CTAs, a `Grid`/table is lighter. Demo: `/pricing-demo`. --- # Process monitor URL: https://mateu.io/ux-patterns/process-monitor/ > Monitored automation processes with a health dot, OK/warning/error counters and a fix action. **Status:** ✅ Implemented ## Intent Answer "are the automations healthy?" in one glance — each integration/robot as a row with a health dot, the systems it touches, its OK/warning/error counters — and put the *fix* one click away when something needs attention. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `ProcessMonitor` component: a list of `ProcessItem`s. Each row shows a colored `status` dot (`ok | warning | error`), the process `name` with its `systems` joined ` · ` in muted small text below, right-aligned counters (`✓ 847 OK` always; `⚠ warnings` and `⛔ errors` only when greater than zero) and, when `actionLabel` + `actionId` are present, a small warning-styled button. ```java @Section("Automatizaciones") Component monitor = ProcessMonitor.builder() .items(List.of( ProcessItem.builder().id("credit").name("Facturación a Crédito") .systems(List.of("OHIP", "OIC", "Voxel")) .ok(847).warnings(6).errors(0).status("warning") .actionLabel("Solucionar").actionId("fixCredit").build(), ProcessItem.builder().id("sales").name("Comercializadora") .systems(List.of("OHIP", "ERP Fusion A/R")) .ok(418).warnings(0).errors(0).status("ok").build())) .build(); ``` ![Process monitor](/images/docs/process-monitor/process-monitor.png) The fix button dispatches the standard `action-requested` event with the **item's** `actionId` and **no parameters** — each process points at its own remediation action (open the failed batch, retry, navigate to the detail). ## When to use it Use a `ProcessMonitor` on **operations/health screens** — nightly interfaces, billing robots, channel synchronizations — where each row is a process, not a data record. For numeric KPIs and drill-in tiles use a [Dashboard](/ux-patterns/dashboard/) (it composes well as a dashboard panel); to narrate one process's events over time use a [Timeline](/ux-patterns/timeline/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/process-monitor-demo`. --- # Progress steps URL: https://mateu.io/ux-patterns/progress-steps/ > Show where a multi-step process stands — a checkout, an onboarding, an approval. **Status:** ✅ Implemented ## Intent Show a user *where they are* in a linear, multi-step process — a checkout, an onboarding, an approval chain — as a row of numbered steps, so what's done, what's active and what's ahead reads at a glance. Unlike a `Wizard` (which *drives* a multi-step form), `ProgressSteps` only **visualizes** progress. Use it to annotate any screen with a status bar; drive the actual navigation however you like. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `ProgressSteps` component: one `Step` per stage, each with a title, optional description and a `status` of `"done"`, `"current"` or `"upcoming"` (the default). Done steps show a check mark and a filled dot; the current step is ringed; upcoming steps are muted. ```java @Section("Progress") Component progress = ProgressSteps.builder() .steps(List.of( Step.builder().title("Cart").description("3 items").status("done").build(), Step.builder().title("Address").description("Madrid").status("done").build(), Step.builder().title("Payment").description("Enter your card").status("current").build(), Step.builder().title("Review").status("upcoming").build(), Step.builder().title("Done").status("upcoming").build())) .build(); ``` ![Checkout progress](/images/docs/progress-steps/checkout.png) The renderer is dependency-free, themes through the standard CSS variables, and works in dark mode. The connector line before each done/current step is highlighted so the "filled" portion of the bar tracks progress. On mobile (React Native) the same steps render as a compact vertical stepper. ## When to use it Use `ProgressSteps` to **orient** the user inside a process you render across several screens or sections. For a self-driving multi-step form, use a `Wizard` instead. Demo: `/steps-demo`. --- # Compare and merge records URL: https://mateu.io/ux-patterns/record-merge/ > Two (or more) records of the same type side by side, the differences highlighted, a pick per field — "use the value from A" or a typed one — and a merge action that receives the result. **Status:** ✅ Implemented · `@Experimental` ![Two duplicate guest profiles side by side, the rows that differ highlighted](/images/docs/record-merge/merge.png) ## Intent Some decisions are taken field by field over two versions of the same thing: merging **duplicate customer profiles**, resolving an **edit conflict** (your version against the stored one), reviewing what a **sync** is about to overwrite. A form with one radio per attribute works, but it reads like a form; the screen people know shows the records in **columns**, marks what differs and lets them pick a side for each row. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Return a `RecordMerge` anywhere in the page's components: one `MergeRecord` per column, one `MergeField` per row with the row's value in each record (in the records' order), and the action that merges. ```java RecordMerge.builder() .title("Guest profiles 1021 and 3388 look like the same person") .records(List.of( new MergeRecord("1021", "Profile 1021", "Created 3 Mar 2021 · 12 stays"), new MergeRecord("3388", "Profile 3388", "Created 9 Sep 2026 · 1 stay"))) .fields(List.of( MergeField.of("lastName", "Last name", "García López", "Garcia"), MergeField.of("email", "Email", null, "ana.garcia@example.com"), MergeField.of("phone", "Phone", "+34 600 111 222", "+34 699 333 444").withEditable(true), MergeField.of("address", "Address", "C/ Mayor 1", "Calle Mayor 1, 07001 Palma") .withEditable(true).withChosen("3388"))) .mergeActionId("mergeProfiles") .mergeLabel("Merge into profile 1021") .parameters(Map.of("survivor", "1021", "duplicate", "3388")) .build() ``` The merge action receives the picks next to the component's own `parameters`: | Parameter | Value | |---|---| | `_merged` | `fieldId → value`: the resulting record | | `_choices` | `fieldId → record id` it was taken from, or `"custom"` when it was typed | ```java public Object mergeProfiles(HttpRequest httpRequest) { var parameters = httpRequest.runActionRq().parameters(); var merged = (Map<String, Object>) parameters.get("_merged"); customers.merge((String) parameters.get("survivor"), (String) parameters.get("duplicate"), merged); return new Message("Profiles merged"); } ``` The server settles what every renderer would otherwise compute on its own: each row is padded (or cut) to one value per record, a row **differs** when its values are not all the same (compared as trimmed text; a missing value is blank), and the value picked to begin with is the one `withChosen` names or else the first record with a value. The picks themselves are client-side state — nothing reaches the server until the merge. ### Options | Parameter | Effect | |---|---| | `records` | the columns, in order — two or more | | `fields` | the rows; `MergeField.of(id, label, values…)`, `withChosen(recordId)`, `withEditable(true)` | | `differencesOnly` | the **Show only differences** switch starts on | | `mergeLabel` | the button's label (default **Merge**) | | `parameters` | sent with the merge action, next to `_merged` / `_choices` | ## Accessibility Each row is a native radio group, so it works with the keyboard as is: Tab moves between rows, the arrow keys pick within one. Every pick has a full name — **"Use value from Profile 3388 for Email"** — and a differing row says *differs* in text, not only in colour. The summary under the result ("7 fields: 5 differ; 1 typed by hand") is a polite live region. ## Where it works - **Vaadin** — the shared `mateu-record-merge` element (a table, scrolling sideways when the records do not fit). - **Redwood (Oracle VB)** — the RecordMerge atom on Redwood tokens. - **React Native** — one card per field (columns do not fit a phone), the same picks and summary. - **IntelliJ plugin** — a Swing grid with a button group per row. - Also from the C# (`new RecordMerge { … }`) and Python (`RecordMerge(...)`) backends, and from YAML (`type: RecordMerge`). Demo: `demo-admin-panel` → `/record-merge-demo` (also **F9**, or **MRG** in the command center). ## Related - [Optimistic locking](/ux-patterns/optimistic-locking/) — when the conflict is detected - [Comparison card](/ux-patterns/comparison-card/) — compare offers rather than records --- # Resource grid URL: https://mateu.io/ux-patterns/resource-grid/ > An availability/selection grid — rooms, tables, slots — with status chips, notes, and a recommended pick. **Status:** ✅ Implemented ## Intent Let the operator assign a physical resource — a room, a table, a berth, a time slot — from a grid that shows each unit's availability state at a glance, disables the unavailable ones, and highlights the recommended pick. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `ResourceGrid` component: a component-level `actionId`, a fixed `columns` count (0/absent → responsive auto-fill), an optional `recommendedLabel` (default "Recommended"), and a list of `ResourceItem`s. Each card shows a big `title`, a muted `subtitle`, a `statusLabel` chip (`statusColor` from the badge palette) and an optional colored `note` line. `disabled(true)` greys the card out and blocks clicks; `recommended(true)` adds an accent border plus a floating mini-tag; `selected(true)` marks the current choice. ```java @Section("Asignar habitación") Component rooms = ResourceGrid.builder() .actionId("pickRoom").columns(4).recommendedLabel("RECOMENDADA") .items(List.of( ResourceItem.builder().id("1201").title("1201").subtitle("Ocupada") .statusLabel("Sucia").statusColor("contrast").disabled(true).build(), ResourceItem.builder().id("1204").title("1204").subtitle("Ocean Suite") .statusLabel("Inspeccionada").statusColor("success") .recommended(true).selected(true).build(), ResourceItem.builder().id("1206").title("1206").subtitle("Libre") .statusLabel("Limpia").statusColor("success") .note("Ducha averiada").noteColor("error").build())) .build(); ``` ![Resource grid](/images/docs/resource-grid/resource-grid.png) Clicking an **enabled** card dispatches the standard `action-requested` event with the component-level `actionId` and parameters `{ "_item": id }`; disabled cards never dispatch. ## When to use it Use a `ResourceGrid` to **pick one unit from a set of physical resources** where the spatial/status overview matters — room assignment in a check-in wizard, table allocation, dock scheduling. To pick an entity from a large searchable collection use an [Entity Picker](/ux-patterns/entity-picker/); to present a paid upgrade next to the assigned unit pair it with an [Offer card](/ux-patterns/offer-card/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/resource-grid-demo`. --- # Saved views URL: https://mateu.io/ux-patterns/saved-views/ > Name and reuse a whole set of listing conditions — keyword, filters, ranges — and open the listing with your default view. **Status:** ✅ Implemented ## Intent Power users return to the same slices of data every day: "my pending invoices", "arrivals this week", "high-value bookings". Rebuilding the filter set every time is a tax; bookmarking URLs is invisible and personal-toolbar-dependent. **Saved views** make the condition set a first-class, named thing on the listing itself. ## Solution Every crud/listing's smart search bar has a **bookmark button** on the right. It opens the views panel: - **Save current view as…** — snapshots the whole condition set (keyword chip, filter values, range bounds, multi-selects) under a name. Saving an existing name replaces it. - **Click a view** — clears the current conditions, applies the view's and re-runs the search. - **★** — marks the view as the listing's **default**: the listing opens with it applied whenever the URL carries no explicit filter params (an explicitly shared/bookmarked URL always wins). Starring again clears the default. - **✕** — deletes the view. No annotations or server code needed — it works on every listing that shows the smart search bar, in every design system. ## Storage & scope Views are stored client-side (localStorage, key `mateu-saved-views`), **per listing route** and per browser origin — the same granularity as the URL filter sync. They are personal to the browser profile; for team-shared slices, share the listing URL (filters sync to it) or model the slice server-side. ## Related - [Filters & Listing](/ux-patterns/filters-and-listing/) — the smart search bar being snapshotted - [Bulk actions](/ux-patterns/bulk-actions/) — act on the rows the view surfaces --- # Sticky sections index URL: https://mateu.io/ux-patterns/sections-index/ > A docs-style long page with a sticky table-of-contents index and pinned sections. **Status:** ✅ Implemented — `@Toc`, `@Section(sticky = true)` ## Intent Show a long form as a single scrollable page where **everything is visible**, and give the user a sticky index to jump between sections — plus the option to **pin** a key section so it never leaves the viewport. ## Problem A screen with many sections has two common failure modes. Hiding content behind tabs keeps the page short but forces the user to remember where things are and to click around. Stacking everything vertically makes it all visible but turns navigation into endless scrolling, and the reference data you keep looking back at (a guest list, the reservation header) scrolls away just when you need it. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the page class with `@Toc` to render a **sticky index** (table of contents) of its sections in a right-hand sidebar. Clicking an entry scrolls to that section; the entry for the section you're looking at highlights as you scroll. ```java @UI("/checkin/:id") @Toc @Style(StyleConstants.FULL_WIDTH_WITH_PADDING) public class CheckInForm { @Section("Información general de la reserva") ReservationInfo general; @Section("Check-in") CheckInData checkIn; // Pinned: the guest list stays in view while the rest scrolls. @Section(value = "Huéspedes", sticky = true) GuestList guests; @Section("Información cliente") ClientInfo client; // … more sections … } ``` ![Docs-style check-in with a sticky sections index](/images/docs/ux-patterns/sections-index.png) ### Pinned sections — `@Section(sticky = true)` Mark any section `sticky = true` and its card is pinned (`position: sticky`) so it never leaves the viewport while the rest of the page scrolls under it — ideal for a reference list or a summary you keep glancing at. In docs mode the **page header is pinned too**, and multiple sticky sections **stack** neatly under it (each pinned below the previous, with a small gap) instead of overlapping. ### `@Toc` is tri-state | Form annotation | Index | |---|---| | *(absent)* | **Auto** — shown only when there are more than four vertically-stacked sections and the form is not a `@Zones` / horizontal layout | | `@Toc` / `@Toc(true)` | Forced on | | `@Toc(false)` | Suppressed | So a long single-column form gets the index for free; you only reach for the annotation to force it on a shorter form or to turn it off. ### Keyboard shortcuts While the index is shown, `Ctrl+Alt+1..9` jump to the first nine sections (the shortcut number is shown as a faint badge on each index entry). Clicking or pressing a shortcut keeps that entry highlighted even if the section sits near the bottom and can't scroll all the way to the top. See [Keyboard Shortcuts](/ux-patterns/keyboard-shortcuts/). ## Sections vs tabs `@Toc` and tabs solve the same "too many sections" problem in opposite ways — pick per screen: | | Tabs (`@Tab`) | Sections index (`@Toc`) | |---|---|---| | Content | One group visible at a time | Everything visible, stacked | | Navigation | Click a tab | Scroll, or click/keyboard-jump in the index | | Best for | Occasional users, compact screens | Power users reviewing a whole record top-to-bottom | | Pairs with | `@Compact`, `@Zones` | `@Section(sticky)`, full-width | To turn a tabbed section into indexed sections, promote each `@Tab` group to its own top-level `@Section` (a `@Tab` inside a nested `@Inline` type groups into tabs, not sub-sections — the split has to happen at the top level). ## Principles served - **Minimize navigation** — the whole record is visible and one keystroke away - **Workflow over screens** — reference sections stay pinned while you work through the rest - **Keyboard-first** — jump to any section without the mouse --- # Session expiry without losing work URL: https://mateu.io/ux-patterns/session-expiry/ > A 401 mid-action hands control to your re-auth flow and retries the same request — the form state survives. **Status:** ✅ Implemented ## Intent The user spends twenty minutes on a form; the token expires; Save returns 401. The naive handling — redirect to login — destroys the work. The right contract: **pause the action, re-authenticate, retry it**; the page never navigates, the state never unloads. ## Solution When any Mateu request returns **401**, the api client does not fail the action. It hands control to the app's re-auth flow and retries the same request once afterwards — the original action then completes as if nothing happened. Plug your re-auth flow (programmatically, from your app's bootstrap script): ```ts import { onSessionExpired } from 'mateu'; onSessionExpired(async ({ retry, giveUp }) => { const ok = await openLoginPopup(); // your flow: popup, refresh token, SSO iframe… if (ok) { localStorage.setItem('__mateu_auth_token', ok.token); // where Mateu reads the Bearer retry(); // re-runs the failed request, action completes } else { giveUp(); // fail normally (user declined) } }); ``` Or listen to the DOM event (same contract, no imports): ```ts document.addEventListener('mateu-session-expired', e => { e.preventDefault(); // claim it const { retry, giveUp } = e.detail; // …re-authenticate, then retry() or giveUp() }); ``` - The retry happens **once** per request (no loops when the new token is also rejected). - Both web renderers raise it: the Vaadin one from its axios client, the Redwood one from its bridge's single request path. - In the Redwood renderer, 401s that arrive **together** share one event: a tab back from the background whose periodic calls (inbox badge, banner sync) and the user's action all bounce at once triggers a single refresh, and all of them are retried with its token. A request whose token was already replaced while it was in flight (the `visibilitychange` refresh landed first) is simply resent, without raising the event. - A **403 is not a session problem** and never raises the event: the server knows who you are and refuses this (an undeclared action, a missing role). Redwood shows "No tienes permiso para hacer esto." instead of the session message. - With **no handler registered**, behavior is exactly as before: the request fails — the guard is fully opt-in. - Because the page never navigates, everything holds: form values, wizard position, scroll, selection. Combine with the [dirty guard](/ux-patterns/partial-forms/) and [autosave](/ux-patterns/autosave/) for defense in depth. ## Keycloak (the generated bootstrap page): handled for you An app secured with Keycloak through Mateu's generated bootstrap page needs none of the above — the page does it: - it **claims `mateu-session-expired`**, forces a token refresh (`updateToken(-1)`) and retries the request; if the refresh fails the Keycloak session itself is gone (expired, revoked, the realm was reset), so it sends the browser to the **login** instead of leaving a "session is no longer valid" message whose retry resends the same dead token; - it refreshes on **`onTokenExpired`** and again whenever the tab **becomes visible** — browsers throttle timers in background tabs and sleeping laptops, which is how a token expires unnoticed. ## Container-managed login (basic auth / form login): the invisible 302 Behind container-managed auth there is no 401: when the server session dies (e.g. the server restarted), API calls answer a **302 to the login page** — and the browser follows it *transparently*, so the client sees a 200 whose body is the login page's HTML instead of JSON. The user would just see the action silently do nothing. Mateu detects this shape on every response — the request was redirected (the final URL differs from the requested one) **and** the payload is not JSON — and sends the **browser** to that final URL so the user can log in again. A redirect that still answers JSON (e.g. a trailing-slash rewrite) is left alone. This is built into the shared api client; nothing to configure. One limit: if the login page lives on **another origin** without CORS, the browser hides the final URL from the client — that case surfaces as a plain network error instead. ## Related - [Idle-session warning](/ux-patterns/idle-session/) — the client-side counterpart: warn before anything expires - [Autosave](/ux-patterns/autosave/) — shrink the window of unsaved work - [Undo](/ux-patterns/undo/) — recover from the opposite problem --- # Slow connections URL: https://mateu.io/ux-patterns/slow-connections/ > How Mateu behaves when the backend is slow or the network is unreliable — busy feedback, per-action timeouts, retries, offline banner and loading skeletons. **Status:** ✅ Implemented ## Intent Keep an app usable when the backend is slow or the connection is poor, without every screen having to handle it. All of this is built into the framework's transport and shell: you get it on every renderer with no code, and you can tune it per action when the defaults do not fit. ## Problem On a fast backend nobody notices the network. On a slow one, the same UI produces a predictable sequence of bad outcomes: - The user presses **Save**, nothing changes for a moment, and they press it again — now there are two rows. - A page shows nothing at all for several seconds and reads as broken rather than loading. - A failure surfaces as `Network Error` or `timeout of 60000ms exceeded`, which tells the user nothing about what happened or what to do. - The connection drops, and the app explains it once per click, five seconds at a time. ## What you get for free ### Busy feedback on the control you pressed The pressed control is marked busy — dimmed and pulsing, `pointer-events: none`, `aria-busy="true"` — for as long as the action runs. This is deliberately *local*: the global loading veil answers "is the app busy?", but the question a user on a slow link is actually asking is "did my click register?". The marker is the `data-mateu-pending` attribute, so a renderer or an app stylesheet can restyle it: ```css [data-mateu-pending] { outline: 2px solid var(--brand-accent); } ``` > The busy state animates the control's own opacity rather than drawing a `::after` spinner. A pseudo-element on a shadow host is not painted, and `vaadin-button`, `ui5-button` and `oj-c-button` are all shadow hosts — a pseudo-element spinner would show on a plain `<button>` and silently vanish everywhere else. ### No double submission While a given action of a given component is in flight, the same action of the same component is refused before any request is built. This covers the paths the loading veil never could: `background` actions, and keyboard shortcuts, where there is no pointer to block. **Reads are exempt from the block.** The guard exists because a second `POST` of a write means a second row; a second read just means fresher data. Blocking reads would break type-ahead — the search for `mad` would be dropped while the search for `ma` was still in flight, leaving the user looking at stale results. ### Loading skeletons on navigation A route with nothing on screen yet renders a skeleton — a title bar and a few field pairs — after 400 ms. Below that threshold the request usually wins and the user sees nothing at all, which is the right outcome for a wait too short to explain. Once a page HAS content, a re-load keeps the old content under the veil instead: stale content beats a skeleton that throws away context. ### Failures in plain language Transport failures are classified and translated before they reach the user. `Network Error` becomes *"No connection. Your changes have not been sent — check your network and try again."*; a timeout becomes *"The server is taking too long to answer. Your changes may not have been saved."* An aborted request (a navigation, the loop breaker) says nothing at all, because it is not news. When the framework declined to retry on the user's behalf, the toast carries a **Retry** control that re-runs the whole action — request and response handling — so the result lands on the page as if it had worked the first time. ### Offline banner Losing the connection is a *state*, not an event, so it gets a standing strip at the top of the page rather than a toast, and the page is pushed down instead of covered. Recovery is announced briefly before the strip retires. Reachability is not taken from `navigator.onLine` alone — that flag reports the link, not the path, and says "online" on a captive portal or a dead uplink. It is used as a hard negative; the positive comes from our own traffic actually coming back. ### Automatic retries, for reads only A read that hits a timeout or a 5xx is re-sent automatically, up to twice, with an exponential backoff and ±25 % jitter. The route load, listing searches, lookup searches and global search are all recognised as reads. **Writes are never retried automatically.** When a request times out the client does not know whether the server processed it, so repeating a `create` risks a silent duplicate. Writes fail once and offer the user an explicit Retry, where the decision is theirs and informed. ## Tuning it per action :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: One global 60-second ceiling cannot serve both a type-ahead lookup, which should give up in seconds so the user can retype, and a report export, which may legitimately run for minutes. ```java // Give up quickly: the user is waiting on this one. @Action(timeoutMillis = 5000) public void quickLookup() { … } // Batch work: a long ceiling, and safe to re-send after a network blip. @Action(timeoutMillis = 120000, idempotent = true) public Message recalculateTotals() { … } ``` `idempotent = true` declares that re-running the action cannot apply the same change twice, so the client may retry it by itself. Use it only for genuine reads or naturally idempotent writes — reads are detected automatically, so this flag is for the cases the framework cannot infer. Both attributes default to "safe": no declaration means the client's own timeout applies and nothing is ever re-sent without the user asking. ### C\# ```csharp [Button, ActionOptions(TimeoutMillis = 5000)] public Message QuickLookup() => …; [Button, ActionOptions(TimeoutMillis = 120000, Idempotent = true)] public Message RecalculateTotals() => …; ``` ### Python ```python @button() @action_options(timeout_millis=5000) def quick_lookup(self): ... @button() @action_options(timeout_millis=120000, idempotent=True) def recalculate_totals(self): ... ``` ## Verifying it `e2e/slow-network-probe.mjs` drives a running app under a throttled, failing and offline network and asserts what the user sees — skeleton, busy control, no double submit, banner, plain-language error, working Retry, read-recovers/write-does-not. Run it against any SUT app: ```bash cd e2e && node slow-network-probe.mjs BASE=http://localhost:8081 node slow-network-probe.mjs ``` It exits non-zero on the first failed check, so it can gate a change to the transport layer. ## Redwood / Visual Builder This renderer has its own transport (`apps/redwood/poc/transport.mjs`, plain `fetch`), so the guarantees are implemented again in `poc/resilience.mjs` rather than inherited. The behaviour is the same — per-action timeout, reads retried automatically and writes never, honest connectivity tracking, no double submit, plain-language errors, busy bar, offline band, loading skeleton, busy state on the pressed control, and a Retry that re-runs the whole action. Three differences worth knowing, all forced by `fetch`: - It has **no timeout**, so one is imposed with `AbortController`; without it a request can hang forever with no error and no end. - It does **not reject on a 4xx/5xx** — it resolves with `res.ok === false`, so the status has to be read and attached to the error by hand. - A network failure is a bare `TypeError`, with no code to switch on. ```bash cd frontend/web/monorepo/apps/redwood && npm run serve # :9006, backend demo-vb en :9005 cd e2e && node vb-slow-network-probe.mjs ``` ## Related - [Empty states and skeletons](/ux-patterns/empty-states-and-skeletons/) — the developer-declared `Skeleton` component - [Autosave](/ux-patterns/autosave/) — `background` actions, which are exempt from all of the above by design --- # Smart search URL: https://mateu.io/ux-patterns/smart-search/ > A standalone, search-first page — the Oracle Redwood "Smart Search" page template. **Status:** ✅ Implemented ## Intent Give users a dedicated search page for a collection: an optional intro line under the page title, the smart search bar with typed filter facets and chips, and the results collection — without the hero chrome of a landing page and without the New/Edit chrome of an entity crud. ## Problem A routed `Listing` preloads its rows and reads as "a grid page"; a crud adds create/edit affordances. When the task is "search across X" — assets, knowledge articles, any record finder — you want the search field to be the page's focus and the page to start empty, waiting for the user. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `SmartSearchPage<Filters, Row>` and implement `search(SearchRequest, HttpRequest)` exactly like any [listing](/java-user-manual/build/capability-listings/) (the archetype already declares `Searchable` and `Filterable<Filters>` for you). It composes the optional `pageSubtitle()` intro line over the standard smart-search listing. It is read-only and starts **empty** (the user searches). ```java @UI("/smart-search-demo") @Title("Smart Search") public class AssetSearch extends SmartSearchPage<AssetFilters, AssetRow> { public enum Zone { Warehouse, Office, Fleet } public record AssetRow(String id, String name, Zone zone, LocalDate acquired, int units) {} public static class AssetFilters { String name; Set<Zone> zones; // multi-select facet DateRange acquired; // from–to date facet } @Override protected String pageSubtitle() { return "Find assets by name, zone or acquisition date"; } @Override public ListingData<AssetRow> search(SearchRequest request, HttpRequest httpRequest) { // query your use case / repository with // request.searchText() + filters(request) + request.pageable() return ListingData.from(/* … */ rows); } } ``` ![Smart search](/images/docs/smart-search/smart-search-demo.png) - The `Filters` fields become the **facets** of the [smart search bar](/ux-patterns/filters-and-listing/#the-smart-search-bar); typed fields get typed widgets — `DateRange`/`NumberRange` render from–to ranges, a `Set<SomeEnum>` renders a multi-select with the enum constants as options. - The page starts **empty** (search-first) and searches on enter. Add `@Trigger(type = TriggerType.OnLoad, actionId = "search")` on the class to preload results. - Results default to a table (`GridLayout.auto`); override `gridLayout()` to force `list`, `cards`, `masterDetail` or `tree`. - Works on every renderer and on the .NET (`SmartSearchPage<TFilters, TRow>`) and Python (`SmartSearchPage[F, R]`) backends — see the [parity matrix](/reference/parity/). ## Before the first search (`preSearchContent`) A search-first page does not have to open on an empty listing. Override `preSearchContent(rq)` with what the user should see until they search — recent items, saved searches, a small dashboard, tips: ```java @Override protected Component preSearchContent(HttpRequest rq) { return EmptyState.builder().icon("🔎").title("Search to get started") .description("Recently viewed: " + recent(rq)).build(); } ``` It stands in for the results until the first search answers, and never comes back afterwards — a later empty result shows the normal empty state. Fluent: `Listing.builder().preSearchItem(...)`. ![Pre-search content before the first search](/images/docs/smart-search/pre-search.png) ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Smart search page (typed facets, chips, search-first) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `preSearchContent` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ## Redwood parameter and slot reference What the Redwood `smart-search-page` template and its `smart-filter-search` pattern expose, and what Mateu gives you for them. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `smartFilters.filtersMetadata` | the `Filters` class fields, typed: `DateRange`/`NumberRange` → from–to widgets, `Set<Enum>` → multi-select | ✅ | | `smartFilters.appliedFilters` / `value` | applied conditions render as removable chips; state round-trips through the component state and the URL | ✅ | | `smartFilters.resultsData` / `totalCount` | `search(SearchRequest, HttpRequest)` → `ListingData` (`Page` carries `totalElements`) | ✅ | | `smartFilters.askHint` | `pageSubtitle()` sets an intro line; the bar itself has no hint prop | 🟡 | | `smartFilters.autofocus` | `autoFocusOnSearchText` on the listing | ✅ | | `smartFilters.expanded` | — the *Filter by* panel opens on click or typing, never on load (opening it on focus would pop it on page load) | — | | `smartFilters.suggestions` / `suggestionFilters` / `autocompleteSource` | — no suggestion layer; `@Lookup`/`@RestOptions` cover per-field remote options | — | | `showAllTotalCount` / `allTotalCountMessage` | — | — | | `collectionScroller: off \| page` | pagination is the listing's own | 🟡 | | `selectContext` | `RecordSwitcherSupplier` on the page (header switcher, `type = context`) | ✅ | | **Slot** default (results) | the listing; `gridLayout()` picks `table`, `list` or `cards` | ✅ | | **Slot** `main` + **`dashboard`** (pre-search content) | `preSearchContent(rq)` → `Listing.preSearch` | ✅ | | **Slot** `search` | the smart search bar is the page's own | ✅ | | **Slot** `announcement` (aria-live) | `UICommand.announce(text)` from any action | ✅ | | `smartFiltersChangedAction` | chip add/remove and facet toggles re-run `search` automatically | ✅ | ## When to use it Use smart search when **searching is the task** but you want a workbench page, not a landing page: record finders, asset/article lookup, cross-team search tools. Prefer [hero search](/ux-patterns/hero-search/) for a distraction-free entry point (public catalogs, home pages), and a plain `AutoCrud`/`Listing` when the user works the collection (edits, exports, dense scanning). --- # Split View URL: https://mateu.io/ux-patterns/split-view/ > Work on a collection without ever leaving the collection. **Status:** ✅ Implemented — `@SplitCrud` ## Intent Work on a collection without ever leaving it. ## Problem The list → detail → back flow forces users to lose their position in the list, their active filters, and their scroll position on every round trip. Reviewing forty orders pays that cost forty times. This is the root cause of the *CRUD Tunnel* anti-pattern. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Annotate the `Crud` with `@SplitCrud`. The framework renders the list on the left and the detail on the right, in a master-detail split layout. Selecting a row loads the detail panel in place instead of navigating to a new route. ```java @UI("/orders") @SplitCrud public class OrdersCrud extends AutoCrud<Order> { @Override public CrudStore<Order> store() { return new OrderStore(); // your CrudStore<Order> } // nothing else needed } ``` The URL still updates (`/orders/42`, `/orders/new`) so deep linking and browser history work correctly. ## Structure ``` ┌─────────────────────┬──────────────────────────┐ │ Filters │ │ │ ───────────────── │ Detail / form │ │ Row 1 │ │ │ Row 2 ◀ selected │ Field A ___________ │ │ Row 3 │ Field B ___________ │ │ ... │ │ │ │ [Save] [Delete] │ └─────────────────────┴──────────────────────────┘ ``` ## Actions available The split layout wires up these actions automatically: | Action | Available | Description | |--------|-----------|-------------| | `view` | always | Opens selected row in detail panel | | `new` | always | Opens creation form in detail panel | | `edit` | always | Switches detail panel to edit mode | | `save` / `create` | always | Saves changes; list refreshes automatically | | `cancel-edit` | always | Cancels the current edit, reverts to view mode | | `delete-edit` | always | Deletes the record from within the detail panel | | `cancel-view` | **not shown** | Hidden — the list is already visible, no need to go back | | `cancel-new` | **not shown** | Hidden — click another row or elsewhere to leave | ## Principles served - **Preserve context** — the list stays visible and interactive - **Minimize navigation** — zero page transitions for the common case ## Hierarchical collections When the collection is a **tree** rather than a flat list — categories inside categories, an org chart, a folder structure — render the master list as an expandable tree grid (`gridLayout() = GridLayout.tree`) on the same `@SplitCrud`. See [Tree CRUD](/ux-patterns/tree-crud/). --- # Stat / KPI tile URL: https://mateu.io/ux-patterns/stat/ > A compact KPI — a big number, a trend delta and an inline sparkline. **Status:** ✅ Implemented ## Intent Show a single metric at a glance — revenue, active users, churn — as a big number with its recent trend (a delta and an inline sparkline), so the value *and its direction* read together. Row several up for a KPI band. `Stat` complements `MetricCard`: where `MetricCard` shows a value + trend label, `Stat` adds the **sparkline** so you see the shape of the recent history. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Stat` component: a `label`, a big `value` with optional `unit`, a `delta` with a `trend` of `"up"`, `"down"` or `"flat"` (which colors the delta green / red / grey and picks the sparkline color), and a `spark` list of numbers drawn as an inline sparkline. An `actionId` makes the whole tile clickable (drill-in). ```java Stat.builder() .label("MRR").value("48.2").unit("k€") .delta("+7.4%").trend("up") .spark(List.of(30.0, 32.0, 31.0, 35.0, 40.0, 42.0, 48.0)) .actionId("openMrr") .build(); ``` Put several inside a `HorizontalLayout` for a KPI band: ```java @Section("This month") Component stats = HorizontalLayout.builder() .style("gap: 1rem; flex-wrap: wrap;") .content(List.of(mrr, activeUsers, churn, nps)) .build(); ``` ![KPI stats](/images/docs/stat/kpi-stats.png) The renderer is dependency-free (an inline SVG sparkline), themes through the standard CSS variables, and works in dark mode. On mobile (React Native) and in the IntelliJ plugin the sparkline is drawn natively. ## When to use it Use `Stat` for **at-a-glance KPIs with a trend**. For a value without a sparkline, or for dashboard tiles wired into the `Dashboard` archetype's scoreboard, use `MetricCard`. Demo: `/stat-demo`. --- # Status list URL: https://mateu.io/ux-patterns/status-list/ > Rows with an icon, a title, a status chip and/or an action — incidents, side-effects checklists, pending items. **Status:** ✅ Implemented ## Intent Show a set of heterogeneous items that each carry a *state* or need a *one-off action* — open incidents on a room, the side-effects checklist of a confirmation ("key will be encoded", "police report sent automatically"), pending verifications — without building a full CRUD for them. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `StatusList` component: one `StatusItem` per row, each with an `icon` (emoji) — or an `avatar` (short text like a person's initials, rendered inside a circular avatar; takes precedence over the icon) — a `title`, a muted `description`, and on the right either a `status` chip (`statusColor` from the badge palette: `normal`, `success`, `warning`, `error`, `contrast`) and/or a small button (`actionLabel` + `actionId`). Set `compact(true)` on the list to tighten the row padding for dense screens (e.g. a guests-in-the-room list on a check-in confirmation), and `frameless(true)` to keep the divider lines between rows but drop the outer border — for a list already framed by its host (typically inside a `@Section` card, where the extra frame is redundant). ```java @Section("Estado") Component checklist = StatusList.builder() .items(List.of( StatusItem.builder().id("ac").icon("🌡") .title("Aire acondicionado con ruido") .description("Habitación 901 · Reportado 28 Apr · Mantenimiento avisado") .status("En curso").statusColor("normal").build(), StatusItem.builder().id("key").icon("🔑") .title("Grabar llave / pulsera") .description("Complemento de llave digital") .actionLabel("Grabar").actionId("encodeKey").build(), StatusItem.builder().id("ses").icon("✓") .title("Parte viajeros (SES)") .description("Se enviará automáticamente al confirmar el check-in") .status("Automático").statusColor("success").build())) .build(); ``` ![Status list](/images/docs/status-list/status-list.png) An item's button dispatches the standard `action-requested` event with the **item's** `actionId` and parameters `{ "_item": id }`, so one `@Action` method can serve several rows by reading `_item`. Rows without a button are display-only. ## When to use it Use a `StatusList` for **stateful checklists and incident lists** — things that are *about* the current entity but not a collection to browse. To narrate events in chronological order use a [Timeline](/ux-patterns/timeline/); for N-of-M identical subtasks use [Task progress](/ux-patterns/task-progress/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/status-list-demo`. ## Related - `BulletedList` — the lightweight sibling: a plain `<ul>` of text items, for read-only enumerations (preferences, highlights) without the row chrome. Also available declaratively: `@BulletedList` on a `List<String>` field. - [Notice](/ux-patterns/notice/) — a compact inline banner for a single highlighted line. --- # Task-Centric Page URL: https://mateu.io/ux-patterns/task-centric/ > A screen designed around a task, not an entity. **Status:** Composition — no new primitive needed ## Intent A screen designed around a task, not an entity. ## Problem "Edit order" forces the user to know which fields to touch and in what order. "Confirm shipment" presents exactly what is needed for that specific job. The former exposes everything; the latter exposes only what the task requires. ## The distinction | Entity-centric | Task-centric | |---|---| | Shows all fields of the entity | Shows only fields relevant to this task | | Generic "Save" action | Named action that completes the work | | User decides what to change | Screen guides the user to the outcome | | One screen for all operations | One screen per distinct workflow step | ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Define a view class that exposes only the fields relevant to the task, plus the actions that complete it. There is no new annotation — this is the **Workflow over screens** principle applied at design time. ```java // Entity-centric (avoid for complex tasks) @UI("/orders/:id/edit") public class EditOrder { private String ref; private LocalDate date; private String customerId; private List<OrderLine> lines; private String notes; private String internalCode; // ... many more fields public void save() { ... } } // Task-centric (preferred) @UI("/orders/:id/confirm-shipment") public class ConfirmShipment { private LocalDate shippedDate; private String trackingNumber; private ShippingCarrier carrier; @Button(buttonStyle = ButtonStyle.primary) // the one primary action @Action(validationRequired = true) public ConfirmationReceipt confirm() { ... } @Action(confirmationRequired = true) public OrderDetail cancel() { ... } } ``` Destructive or irreversible actions carry `@Action(confirmationRequired = true)`. ## Structure ``` Confirm shipment — Order #4521 Shipped date [2024-03-15] Carrier [DHL ▼] Tracking [1Z999AA10123456784] [Cancel] [Confirm shipment →] ``` ## Principles served - **Workflow over screens** — the screen exists to complete a job - **Progressive complexity** — irrelevant fields stay hidden - **Recoverability** — confirmation gate on destructive paths --- # Task progress URL: https://mateu.io/ux-patterns/task-progress/ > A subtask completion banner — N-of-M pills and a call to action for the next pending item. **Status:** ✅ Implemented ## Intent Tell the operator *how far along a repeated subtask is* and pull them into the next one — "reservation with 4 pax, 1 registered, add the next" — as a banner that cannot be missed, instead of a counter buried in a corner. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `TaskProgress` component: a `label`, integer `total` and `done` counts (rendered as `1/4 2/4 3/4 4/4` pills, filled up to `done`), and an optional right-aligned button (`actionLabel` + `actionId`). While incomplete the banner is warning-tinted; when `done == total` it turns success-tinted and the button disappears. ```java @Section("Guests") Component pax = TaskProgress.builder() .label("Booking for 4 guests. Register the additional guests.") .total(4).done(1) .actionLabel("Add next guest").actionId("addPax") .build(); ``` ![Task progress](/images/docs/task-progress/task-progress.png) Clicking the button dispatches the standard `action-requested` event with the component's `actionId` and **no parameters** — typically an `@Action` method that opens the next subtask (e.g. the registration form for the next guest). The button is hidden when `actionLabel`/`actionId` are absent. ## When to use it Use `TaskProgress` when a task contains a **known number of identical subtasks** and you want completion status plus a one-click path to the next one. For the stage of a linear flow use [Progress steps](/ux-patterns/progress-steps/); for heterogeneous pending items use a [Status list](/ux-patterns/status-list/). See it composed into a whole screen in [Front-office screens](/ux-patterns/front-office/). Demo: `/task-progress-demo`. --- # Task queue URL: https://mateu.io/ux-patterns/task-queue/ > A grouped work queue rail — arrivals, departures, in-house — with selectable cards and badges. **Status:** ✅ Implemented ## Intent Give the operator their *work for the shift* as a vertical rail of grouped cards — "Llegadas hoy", "Salidas hoy", "En hotel" — so picking the next item is one click and the current one stays visibly selected while they work on it. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `TaskQueue` component: a component-level `actionId` plus a list of `QueueGroup`s (small-caps `label` + `QueueItem`s). Each item card shows a `title`, a muted `caption` and a row of badge-palette `Chip`s; `selected(true)` marks the item currently being worked on (accent border + tint). ```java @Section("Salidas hoy") Component queue = TaskQueue.builder() .actionId("openGuest") .groups(List.of( QueueGroup.builder().label("En hotel · late check-out primero") .items(List.of( QueueItem.builder().id("1108").title("Carlos Mendoza") .caption("Hab 1108 · 7N") .badges(List.of(Chip.builder().label("LATE · 18:00").color("warning").build())) .selected(true).build())) .build(), QueueGroup.builder().label("Salida pendiente") .items(List.of( QueueItem.builder().id("901").title("Sophie Laurent") .caption("Hab 901") .badges(List.of(Chip.builder().label("GOLD").color("contrast").build())) .build())) .build())) .build(); ``` ![Task queue](/images/docs/task-queue/task-queue.png) Clicking a card selects it visually and dispatches the standard `action-requested` event with the component-level `actionId` and parameters `{ "_item": id }` — typically an `@Action` method that loads that guest/ticket/case into the main panel. ## When to use it Use a `TaskQueue` as the **left rail of a workspace**: the queue drives which entity the rest of the screen shows. It is the work-queue counterpart of a master list in a [Split View](/ux-patterns/split-view/), and composes naturally into a [Workspace](/ux-patterns/workspace/) with an [Entity header](/ux-patterns/entity-header/) and detail panels — see [Front-office screens](/ux-patterns/front-office/). For a full searchable collection use a CRUD listing instead. Demo: `/task-queue-demo`. --- # Testimonials URL: https://mateu.io/ux-patterns/testimonials/ > A grid of customer quote cards with author and star rating. **Status:** ✅ Implemented ## Intent Show social proof — customer quotes, reviews, endorsements — as a grid of quote cards, each with an author (avatar, name, role) and an optional star rating. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Testimonials` component: a list of `Testimonial`s (quote, author, role, avatar, rating 0–5). The renderer lays them out in an auto-fitting grid; the rating renders as filled/empty stars. ```java @Section("Testimonials") Component testimonials = Testimonials.builder() .items(List.of( Testimonial.builder() .quote("We shipped our internal tool in a weekend. Zero frontend code.") .author("Ada Lovelace").role("CTO, Analytical Engines") .avatar("👩‍💼").rating(5).build(), Testimonial.builder() .quote("Solid, pragmatic, and the AI chat is a genuine time-saver.") .author("Grace Hopper").role("VP Engineering").avatar("👩‍🔬").rating(4).build())) .build(); ``` ![Customer voices](/images/docs/testimonials/customer-voices.png) The renderer is dependency-free, reflows on narrow viewports, themes through the standard CSS variables and works in dark mode. `avatar` accepts an emoji or an image URL. ## When to use it Use `Testimonials` for **social proof** on landing/marketing pages. Demo: `/testimonials-demo`. --- # Timeline / activity feed URL: https://mateu.io/ux-patterns/timeline/ > Show a chronological sequence of events — an audit trail, an order history, a changelog. **Status:** ✅ Implemented ## Intent Show *what happened, in order* — an order's journey, an audit trail, a case history, a release changelog — as a vertical feed so the sequence and timing read top-to-bottom. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `Timeline` component: one `TimelineItem` per event, each a dot on a vertical rail with a title, an optional description, a free-form `timestamp` label and an emoji `icon`. `color` tints the dot; an `actionId` makes the entry clickable (dispatches the standard `action-requested` event). ```java @Section("History") Component feed = Timeline.builder() .items(List.of( TimelineItem.builder().title("Order placed") .timestamp("Mar 3 · 09:02").icon("🛒").color("#3b82f6").build(), TimelineItem.builder().title("Shipped") .description("Tracking #RH-88213 — click for details") .timestamp("Mar 4 · 08:15").icon("🚚").color("#f59e0b") .actionId("openTracking").build(), TimelineItem.builder().title("Delivered") .timestamp("Mar 5 · 13:22").icon("✅").color("#10b981").build())) .build(); ``` ![Order activity](/images/docs/timeline/activity-feed.png) The renderer is dependency-free, themes through the standard CSS variables, and works in dark mode. The rail line connects consecutive dots and stops at the last entry. ## When to use it Use a Timeline to **narrate** a sequence of past events. The `timestamp` is a free-form label (`"2h ago"`, `"Mar 3 14:20"`) so you format it however you like. For editable/interactive histories, make entries `actionId`-clickable and open a detail view. Demo: `/timeline-demo`. --- # To-do list URL: https://mateu.io/ux-patterns/to-do-list/ > The user's pending work as grouped, actionable task cards — the Redwood "To-do list" page template. **Status:** ✅ Implemented ## Intent Give users a single place with everything pending on their plate: buckets like *Today / This week / Later* (or per status), each labelled with its counter, and cards with due-date and priority badges — where clicking a task **acts on it** (typically navigating to it) instead of selecting it for a side detail pane. ## Problem A generic listing forces to-dos into rows and columns, and a collection-detail splits attention between a list and a detail pane. A personal work queue is neither: it is a flat, prioritized set of actionable cards organized by urgency. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `TodoList<Row>` and implement `rows()`, `idOf`, `titleOf`, `groupOf` and `actionOn`. The archetype composes a `TaskQueue` with one counted group per bucket; clicking a card runs `actionOn(row)` — return a `URI` to navigate, or any other Mateu action result. ```java @UI("/todo-list-demo") @Title("Front desk tasks") public class FrontDeskTasks extends TodoList<FrontDeskTasks.Task> { public record Task(String id, String title, String guest, String bucket, String due, String priority) {} @Autowired FrontDeskTaskService tasks; @Override protected List<Task> rows(HttpRequest httpRequest) { return tasks.pending(); // your use case / repository } @Override protected String idOf(Task t) { return t.id(); } @Override protected String titleOf(Task t) { return t.title(); } @Override protected String captionOf(Task t) { return t.guest(); } @Override protected List<Chip> badgesOf(Task t) { return List.of(new Chip(t.due(), "normal"), new Chip(t.priority(), "warning")); } @Override protected String groupOf(Task t) { return t.bucket(); } @Override protected Object actionOn(Task t, HttpRequest httpRequest) { return URI.create("/bookings/" + t.id()); // clicking navigates to the task } } ``` ![To-do list](/images/docs/to-do-list/todo-list-demo.png) - **Buckets** render in first-appearance order with `name (count)` labels — override `groupOrder()` for an explicit order and `groupLabel(group, count)` for the label format. - **Badges** (`captionOf` / `badgesOf`) carry the due date and priority of each card. - When nothing is pending, the page shows an **"All caught up!"** empty state — override `emptyState()` to change it. - Works on every renderer and on the .NET (`TodoList<TRow>`) and Python (`TodoList[Row]`) backends — see the [parity matrix](/reference/parity/). ## Redwood parameter and slot reference What the Redwood `task-organizer-page` template exposes, and what Mateu gives you for it. This is the **most fully covered template of the set** — its API is deliberately minimal. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `pageTitle` | `@Title` | ✅ | | `primaryAction {label, icon, display}` + `spPrimaryAction` | a `Button` field with its `@Action` (the fluent `Button` carries `iconOnLeft`/`iconOnRight` and `disabled`) | ✅ | | `displayOptions.density: standard \| compact` | `@Compact`, set on the view rather than as a template option | 🟡 | | `displayMode` | the renderer adapts to the viewport | 🟡 | | **Slot** default (the task cards) | `rows()` + `idOf`/`titleOf`/`groupOf`, enriched by `captionOf`/`badgesOf`, composed as a `TaskQueue` | ✅ | | **Slot** `search` | the app-level smart search bar / ⌘K palette, not a page slot | 🟡 | Mateu adds bucket ordering and labelling (`groupOrder()`, `groupLabel(group, count)`) and an `emptyState()` override, none of which the Redwood template exposes. ## When to use it Use the to-do list for **personal or team work queues**: approvals, reviews, front-desk tasks, follow-ups. Prefer [collection detail](/ux-patterns/collection-detail/) when browsing a collection calls for an in-place detail pane, and a [smart search](/ux-patterns/smart-search/) page when finding the item is the hard part. --- # Tree CRUD URL: https://mateu.io/ux-patterns/tree-crud/ > Browse and edit a hierarchy in place — an expandable tree on the left, the selected node's editor on the right. **Status:** ✅ Implemented — `gridLayout() = GridLayout.tree` + `@SplitCrud` ## Intent Navigate a hierarchy and edit any node without leaving the tree. ## Problem Some data is naturally a tree: categories inside categories, an org chart, a folder/document structure, a bill of materials, a project breakdown. A flat, paginated table cannot express it — pagination shreds the parent/child relationship, and forcing the user to drill down screen by screen (open category → open subcategory → open product → back → back) is the *CRUD Tunnel* anti-pattern applied to a tree, paid once per level. ## Solution Render the master list of a CRUD as an **expandable tree grid**, and pair it with a split view so selecting a node opens its editor in place. Two ingredients: 1. rows that carry a self-referential `children` collection; 2. `gridLayout()` returns `GridLayout.tree`, on a `@SplitCrud` CRUD. ### The row :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java public record CategoryRow( @Priority(value = 1, identifier = true) // becomes the expandable tree column String name, int products, List<CategoryRow> children // the branches ) {} ``` - The first / identifier column becomes the **tree column** — it carries the expand/collapse toggle. - A row with a non-empty `children` list gets an expand toggle; leaf rows leave `children` empty or `null`. - `search()` returns only the **root** rows — each branch expands lazily from its `children` list. ### Homogeneous tree — one editor for every node When every node is the same kind of thing (a category that nests into categories, a folder inside a folder), a plain `AutoCrud` is enough — just switch the layout to `tree`: ```java @UI("/catalog") @SplitCrud public class CatalogTree extends AutoCrud<Category> { @Override public CrudStore<Category> store() { return new CategoryStore(); // your CrudStore<Category> } @Override public GridLayout gridLayout() { return GridLayout.tree; } } ``` `Category` is `Identifiable`, exposes a `List<Category> children`, and its repository returns the **root** categories (each carrying its nested children). Selecting any node opens the `Category` editor in the detail pane; saving refreshes the tree in place. ### Heterogeneous tree — a different editor per node Real workspaces mix node types: a project holds services, a service holds modules, a module holds entities — and each edits with its own form. Drop to the lower-level `Crud<…>` and supply the tree from its lifecycle methods: - a single **row record** describes every node (`label`, a hidden `id`, `children`); - `search()` builds the whole tree once; - `save()` / `edit(id)` **route to the right editor** by decoding the node id; - grouping nodes (a folder, a category header) set **`viewable = false`** so they show no open button and own no editor — only their children are openable. ```java @UI("/workspace") @SplitCrud @NotCreatable @NotDeletable public class WorkspaceCrud extends Crud< Object, Object, Object, NoFilters, WorkspaceRow, String> { private final WorkspaceAdapter adapter; // supplies the tree + the per-node editors @Override public GridLayout gridLayout() { return GridLayout.tree; } @Override public boolean searchable() { return true; } @Override public ListingData<WorkspaceRow> search(SearchRequest request, HttpRequest req) { return ListingData.of(adapter.tree()); // the whole tree, built once } @Override public Object view(String id, HttpRequest req) { return adapter.editorFor(id); } @Override public Object edit(String id, HttpRequest req) { return adapter.editorFor(id); } @Override public String save(HttpRequest req) { String id = req.getString(getIdFieldForRow()); adapter.save(id, req); // route by id — the adapter knows which editor the id belongs to return id; } // @NotCreatable @NotDeletable: never offered @Override public Object creationForm(HttpRequest req) { return null; } @Override public String create(HttpRequest req) { return null; } @Override public void deleteAllById(List<String> ids, HttpRequest req) {} } ``` ```java public record WorkspaceRow( String label, // the tree column @Hidden String id, // real id for openable nodes; synthetic for grouping nodes @Hidden boolean viewable, // false → grouping node: no open button, no editor List<WorkspaceRow> children ) {} ``` The orchestrator's `search()` returns the roots with their children nested; `edit(id)` and `view(id)` inspect the id to return the correct concept's form — in the example above they delegate to a `WorkspaceAdapter` service that owns the per-node routing. ## Structure ``` ┌──────────────────────────┬──────────────────────┐ │ ▾ Electronics │ │ │ ▾ Phones │ Product: iPhone │ │ iPhone ◀ selected│ Name __________ │ │ Pixel │ Price __________ │ │ ▸ Laptops │ │ │ ▸ Home & Garden │ [Save] [Delete] │ └──────────────────────────┴──────────────────────┘ ``` ## Tree is opt-in — the flat layouts are not For a **non-hierarchical** listing you usually choose nothing: a listing you do not configure is a **table**, at any screen width. Ask for **list** or **cards** with `gridLayout()` when a table is not the right shape. See [Listing layout](/java-user-manual/build/listing-layout/). **tree also changes the data contract**, not just the look: the rows must carry a self-referential `children` list. That is the extra reason to opt in deliberately. ## Principles served - **Preserve context** — the whole hierarchy stays visible and interactive while you edit a node. - **Minimize navigation** — no drill-down/back trips; expand and edit in place. - **Workflow over screens** — the tree *is* the workspace, not a stop on the way to one. ## When to use it - Data that is genuinely a tree: catalogs, org charts, folder/document structures, BOMs, project breakdowns. - **Not** for flat collections — a table / list / cards CRUD (optionally `@SplitCrud`) is simpler and needs no `children` list. ## Related - [Split View](/ux-patterns/split-view/) — the flat (non-hierarchical) master-detail CRUD this pattern builds on. - [Listing layout](/java-user-manual/build/listing-layout/) — every `GridLayout` value and when to reach for each. - [Workspace](/ux-patterns/workspace/) — composing several heterogeneous panels on one screen. --- # Trend chart URL: https://mateu.io/ux-patterns/trend-chart/ > A lightweight line/area chart for a single series — a revenue trend, a metric over time. **Status:** ✅ Implemented ## Intent Show a single metric's shape over time — revenue, signups, latency — as a clean line or area chart, without pulling in a full charting library. `TrendChart` is the middle ground between the `Stat` sparkline (tiny, inline) and the full `Chart` component (Chart.js, multi-series, interactive): a dependency-free, single-series line/area chart. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Use the `TrendChart` component: a list of `values`, optional x-axis `labels`, a `color` and an `area` flag. The renderer draws an SVG line (area-filled when `area` is true), marks the min and max points and shows per-point tooltips. ```java @Section("Monthly revenue (k€)") Component trend = TrendChart.builder() .title("Revenue 2026") .values(List.of(32.0, 35.0, 33.0, 41.0, 44.0, 48.0, 52.0, 49.0, 58.0, 63.0, 61.0, 72.0)) .labels(List.of("Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec")) .color("#1a73e8") .area(true) .build(); ``` ![Revenue trend](/images/docs/trend-chart/revenue.png) The renderer is dependency-free (inline SVG), themes through the standard CSS variables and works in dark mode. On mobile (React Native) and the IntelliJ plugin the series renders as a compact bar/line chart. ## When to use it Use a `TrendChart` for **one series over time**. For a tiny inline trend use a `Stat` sparkline; for multiple series, axes and interactivity use the `Chart` component. Demo: `/trend-demo`. --- # Undo URL: https://mateu.io/ux-patterns/undo/ > A toast with an Undo button after destructive or bulk actions — recoverability without confirmation friction. **Status:** ✅ Implemented ## Intent Confirmation dialogs tax every operation to protect against the rare mistake. The friendlier contract is **act immediately, offer a way back**: archive the document, show *"Documento archivado — Deshacer"*, and only the mistaken click costs anything. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Return `Message.undoable(...)` from the action: ```java @Button public Message archive(HttpRequest httpRequest) { service.archive(docId); // soft-delete: keep the row restorable return Message.undoable("Documento archivado", "restore", Map.of("docId", docId)); } @Action // only the toast names it: mark it, or strict action mode refuses it public Message restore(HttpRequest httpRequest) { var docId = String.valueOf(httpRequest.runActionRq().parameters().get("docId")); service.restore(docId); return Message.success("Documento restaurado"); } ``` - The toast shows the text plus an **Undo button** (label `undoLabel`; when unset, the renderer's own word for Undo in the app's language) and stays 10 seconds by default. - Clicking Undo dispatches `undoActionId` on the initiator component with `undoParameters` as action parameters — a plain method of the same class that **reverses the effect itself**. - The pattern presumes **soft-delete** (or an equivalent reversible operation): keep the data, flag it, restore on undo. For truly irreversible operations keep `@ListToolbarButton(confirmationRequired = true)` instead — undo and confirmation are complementary, not exclusive. - Works after [bulk actions](/ux-patterns/bulk-actions/) too: pass the affected ids in `undoParameters` and restore them all. ## Related - [Bulk actions](/ux-patterns/bulk-actions/) — the operations most worth undoing - [Concurrent edit conflicts](/ux-patterns/optimistic-locking/) — the other recoverability guard ## On Redwood Oracle's `oj-sp-messages-toast` carries no actions, so an undoable message is shown with JET's own notification — an `oj-messages` (display `notification`) whose `oj-message` puts the Undo `oj-button` in its `detail` slot, the slot JET reserves for links and buttons. Pressing it runs the undo action on the page that produced the message and closes the notification. Demo: moving or resizing a stay on the Room Diary of `demo-vb-pms`. --- # Waterfall detail URL: https://mateu.io/ux-patterns/waterfall-detail/ > A record detail read top-to-bottom as stacked, full-width panels — a composition pattern, not an archetype. **Status:** ✅ Composition pattern (no dedicated archetype needed) ## Intent Present one record as a vertical cascade of full-width panels — header, key facts, then section after section of related content — so the user scrolls the whole story of the record instead of hunting through tabs. Oracle Fusion calls this the **Waterfall detail** template. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The waterfall is a plain `VerticalLayout` of the existing building blocks — an `EntityHeader` for the title/facts strip, then one `Card` (or frameless `@Section`) per topic, often with property lists for the label/value look: ```java @UI("/contracts") @Title("Contract CT-2026-018") public class ContractView implements ComponentTreeSupplier { @Autowired ContractService contracts; @Override public Component component(HttpRequest httpRequest) { var contract = contracts.byRoute(httpRequest); return VerticalLayout.builder() .fullWidth(true) .spacing(true) .content(List.of( EntityHeader.builder() .title(contract.number()) .badges(statusChipsOf(contract)) .facts(factsOf(contract)) .build(), Card.builder().title(new Text("Terms")) .content(propertyListOf(contract)).build(), Card.builder().title(new Text("Lines")) .content(linesTableOf(contract)).build(), Card.builder().title(new Text("Activity")) .content(new Timeline(contract.events())).build())) .build(); } } ``` - **Page width**: annotate `@PageWidth(FIXED)` — a waterfall reads best as a centered, capped column (the renderer's inference already defaults to fixed for this content). - Anchor navigation between sections composes with the `@Toc` sticky sections index. - Alternating `#FBF9F8` / `#F1EFED` panels (the RDS waterfall look) are a `style`/`cssClasses` touch away on each card. ## When to use it Use the waterfall for **read-mostly record stories**: contracts, orders, invoices, dossiers. Prefer [item overview](/ux-patterns/item-overview/) when the record has a strong key-info + tabbed shape, and [general overview](/ux-patterns/general-overview/) when the user jumps between records of the same type. --- # Welcome page URL: https://mateu.io/ux-patterns/welcome-page/ > A friendly introduction to a flow with clear calls to action. **Status:** ✅ Implemented ## Intent Give first-time or occasional users a friendly entry point to a flow: a big hero that explains what this is, one or two clear calls to action, and highlight tiles with the most important information or steps. ## Problem Dropping occasional users straight into a dense operational screen forces them to reconstruct "what do I do first?" every time. A hand-built landing page is easy to write once but tends to drift stylistically from the rest of the app. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `Welcome`. `Button` fields become call-to-action buttons inside the hero; component fields annotated with `@Panel` become highlight tiles on a responsive grid below. ```java @UI("/welcome") @Title("Welcome") public class WelcomeDemo extends Welcome { Button start = Button.builder() .label("Start check-in").actionId("startCheckin") .buttonStyle(ButtonStyle.primary).build(); @Panel(title = "1 · Search the booking") Markdown step1 = new Markdown("Find the reservation by locator, guest name or room.", null, null); @Panel(title = "2 · Verify the guests") Markdown step2 = new Markdown("Scan documents and confirm the cardex.", null, null); @Override protected String heroTitle() { return "Front desk check-in"; } @Override protected String heroSubtitle() { return "Everything you need, in three steps"; } @Action Object startCheckin() { return URI.create("/checkin"); } } ``` ![Welcome page](/images/docs/welcome/welcome-demo.png) The CTA's `actionId` runs the matching `@Action` method — return a `URI` to navigate into the flow. Override `heroImage()` for a background image (a dark overlay keeps text readable). ## The welcome banner element (and the accent strip rule) The hero the archetype renders is the Redwood **Welcome Banner** element — a branded band with a big title, subtitle and optional background image. You can put one at the top of **any** page (archetype or not) with the `@WelcomeBanner` annotation on the view class: ```java @UI("/onboarding") @Title("Onboarding") @WelcomeBanner(title = "Find your flow", subtitle = "Three steps and you are done") public class Onboarding { /* … */ } ``` The banner title falls back to the page `@Title` when left blank. Redwood's anatomy rule: **the accent color strip only shows on pages WITHOUT a welcome banner** — so on any page that carries one (this annotation, or a `HeroSection` anywhere in the content, like `Welcome` and `HeroSearch`), the Redwood renderer suppresses the strip automatically. ## Hero tone The hero band can take one of nine deep tones — the Redwood welcome palette idea, expressed as hues, not as Oracle's swatches: ```java @Override protected HeroTone heroTone() { return HeroTone.pine; } ``` or `@WelcomeBanner(tone = HeroTone.plum)` on any page. `auto` (the default) keeps the renderer's own band. Vaadin, React Native and IntelliJ paint Mateu's palette (ocean `#1f4e79`, pine `#2d5a3d`, lilac `#5b4a7a`, teal `#1f5c5c`, rose `#7a3b4f`, pebble `#5a5550`, slate `#3d4a57`, plum `#5e3557`, sienna `#7a4a2e`, with light ink); Redwood maps each tone onto its welcome banner's `dark-<tone>` background. ![A pine hero](/images/docs/welcome/hero-tone.png) ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Hero + CTAs + highlight tiles | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `@WelcomeBanner` on any page | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Hero tone | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ## Redwood parameter and slot reference What the Redwood `welcome-page` template exposes, and what Mateu gives you for it. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/); this table covers what is specific to this one. **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `pageTitle` (hero title) | `heroTitle()`, or `@WelcomeBanner(title=…)` on any page | ✅ | | `descriptionText` | `heroSubtitle()` / `@WelcomeBanner(subtitle=…)` | ✅ | | `overlineText` (small text above the title) | `@Overline("Reservations")`, or `OverlineSupplier` when it depends on runtime state | ✅ | | `primaryAction` / `secondaryAction` / `secondaryActions` | `Button` fields; the fluent `Button` carries `iconOnLeft`/`iconOnRight`, `disabled` and `actionId` | ✅ | | `backgroundColor`: 9 dark tones + `auto` | `heroTone()` / `@WelcomeBanner(tone=…)` → `HeroTone` (ocean, pine, lilac, teal, rose, pebble, slate, plum, sienna, `auto`) | ✅ | | `illustrationBackground` + `illustrationForeground` (two illustration layers) | `heroImage()` — a single background image with a dark overlay | 🟡 | | `themedImage: pebbles \| none` | ⚪ an Oracle illustration asset; design-system-specific by nature | ⚪ | | `displayOptions.imageStretch: none \| full` | — | — | | `displayOptions.mobileImage` | — | — | | `displayOptions.responsivePadding` | — | — | | `displayOptions.inFlowBack` + `spInFlowBack` | back/cancel affordances approximate it; no explicit in-flow back | 🟡 | | **Slot** default (tiles under the hero) | component fields annotated `@Panel`, on a responsive grid | ✅ | | **Slot** `search` | the app-level smart search bar / ⌘K palette, not a page slot | 🟡 | | `spPrimaryAction` / `spSecondaryAction {actionId}` | the `@Action` method matching the button's `actionId`; return a `URI` to navigate | ✅ | One anatomy rule from Redwood that Mateu applies automatically: **the accent colour strip only shows on pages without a welcome banner**, so any page carrying one — this archetype, `@WelcomeBanner`, or a `HeroSection` anywhere in the content — suppresses the strip. ## When to use it Use a welcome page as the entry route of flows used by **occasional or first-time users** (self-service portals, guided processes, seasonal tasks). Power users working the same screen all day are better served by a [Dashboard](/ux-patterns/dashboard) or by the operational screen itself. --- # Wizard URL: https://mateu.io/ux-patterns/wizard/ > Guide sequential flows with inter-step dependencies. **Status:** ✅ Implemented ## Intent Guide sequential flows where each step depends on what was chosen in earlier steps. ## Problem An onboarding flow where step 3 depends on what was selected in step 1 cannot be safely collapsed into one large form — the user could advance without completing required choices, or see irrelevant fields. Jumping between pages with no intermediate validation breaks the flow. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Extend `Wizard` and declare one field per step; each field's type must implement `WizardStep`. Mateu renders the current step's form, a progress indicator, and navigation buttons automatically. The progress indicator is a bar by default; annotate the wizard with `@WizardProgress(WizardProgressStyle.STEPS)` to show connected step bullets instead (one numbered dot per applicable step with done/current/upcoming states — skipped branching steps are excluded, and every dot shows done on the result screen), or `@WizardProgress(WizardProgressStyle.RAIL)` for the guided-process lateral rail: the step form on the left and a sticky right-hand band with a big `current | total` counter over the vertical step list (demo: `/branching-wizard`). In the Redwood renderer `STEPS` draws the steps as a horizontal train across the top of the page (an `oj-train`; done steps can be clicked to go back, and on narrow screens the same steps are listed vertically), with the wire's Back / Next / completion buttons in the footer; `RAIL` draws the Oracle Redwood Guided Process page template (`oj-sp-guided-process`): the wizard opens on its overview — the wizard's title and `@Subtitle` over the steps as columns side by side, a completed step marked as such — and Start (or Resume) opens the steps one at a time with the step list on the right; the template's own texts (Start, Continue, Cancel, Completed) follow the browser's language. In both renderers `Next` only leaves a step whose required fields (`@NotNull`, `@NotEmpty`, `@NotBlank`, `RequiredSupplier`) are filled in: the browser marks the empty ones and focuses the first, and the server checks them again before moving on (an error message names them). The Back and Next labels go through the app's `Translator` like every other Mateu text (`Back=Atrás` / `Next=Siguiente` in a `messages_<lang>.properties`), or the wizard fixes them with `@WizardLabels(back = "Atrás", next = "Siguiente")`; the completion button's label is its method's `@Label`. State set in **any** step — by the user or by an action — survives navigation in both directions and reaches the completion action, so steps can freely read what earlier (or later) steps produced. ```java // Each step is a plain class or record implementing WizardStep public class AccountTypeStep implements WizardStep { @NotNull AccountType accountType; } public class CompanyDetailsStep implements WizardStep { String companyName; String vatNumber; } // Result step — read-only screen shown after completion public class OnboardingResult implements WizardStep { @PlainText String summary = "Account created successfully."; } // The wizard class @UI("/onboarding") public class OnboardingWizard extends Wizard { AccountTypeStep step1 = new AccountTypeStep(); CompanyDetailsStep step2 = new CompanyDetailsStep(); OnboardingResult result; // null → auto-instantiated after @WizardCompletionAction @WizardCompletionAction @Action(validationRequired = true) Object finish() { accountService.create(step1, step2); result = new OnboardingResult(); // optional: set explicitly for custom data return null; } } ``` ## How it works | Step position | Behaviour | |---|---| | Any intermediate step | Shows **Next →** (and **← Back** after step 1). Validation runs on **Next →**. | | Penultimate step | Shows the `@WizardCompletionAction` button instead of **Next →**. | | Last step | **Read-only result screen.** No navigation buttons. Progress bar shows 100 %. | **The last step field is always the result screen**, whatever its type: **Next →** never reaches it, only the completion action does. It is not a step of the process, so the step indicators leave it out; its `@Label` travels with them as the result's title (`resultTitle` on the `ProgressSteps`), and the Redwood guided process titles its finished screen with it (a translated "Completed" when it has none) without counting it in the `n | total` counter. A wizard with three input steps therefore declares four step fields — the fourth being what the user sees once it is done. The last step is instantiated automatically with its default field values if it is `null` when `@WizardCompletionAction` returns — or the wizard can set it explicitly inside the completion method. A step can carry buttons of its own: its `@Toolbar` methods are drawn under the step's form, and clicking one runs it on the step as the user left it (hydrated with what was typed, not validated — a "Suggest" or "Check" helper works on a half-filled step). The wizard then shows the same step again with whatever the method changed; a `Message` it returns shows over it, and any other answer (a navigation, an overlay) is the response. ```java public class ContactStep implements WizardStep { public String email; @Toolbar @Label("Use my work email") public void useWorkEmail() { email = "me@example.com"; } } ``` The completion method's return value decides where the wizard goes: | Returns | Result | |---|---| | `null` | The result step. | | `Message.error(...)` (or any other object) | That answer, and the wizard stays on the step. | | A `Flux` — typically a [`LongTask`](/ux-patterns/long-running-jobs/) | The progress streams live, then the result step. If the stream emits a `Message.error`, the wizard stays on the step instead. | A completion method declared to return a `Flux` is advertised as an SSE action, so the client receives the progress as it is produced: ```java @WizardCompletionAction @Label("Run end of day") Flux<?> run() { if (!cashiers.closeAll) { return Flux.just(Message.error("Close the open cashiers first.")); } return LongTask.create("Running end of day") .withProgressBar() .run(progress -> Flux.fromIterable(procedures) .map(p -> progress.step(p.run(), p.index() / (double) procedures.size()))); } ``` The result step is built once the stream is over, so whatever the work set on the wizard while it ran (here, the status of each procedure) is on the result screen. Streamed completions are Java-only: the .NET and Python ports have no `LongTask`. The wizard **title** is derived in order: `TitleSupplier.title()` → `@Title` annotation → class name (the dynamic supplier wins over the static annotation). ![Registration wizard — step 1 with progress bar and Next button](/images/docs/ux-patterns/wizard.png) ## Branching — conditional steps Override `stepApplies(String stepFieldName)` to skip steps based on the answers so far. A skipped step is jumped over in **both** directions (Next and Back), excluded from the progress bar, and left out of the accordion / previous-answers recap in the other layout modes. The result step always applies. ```java public class SignupWizard extends Wizard { AccountTypeStep account = new AccountTypeStep(); // asks PERSONAL / COMPANY CompanyDetailsStep company = new CompanyDetailsStep(); PlanStep plan = new PlanStep(); ResultStep result; @Override protected boolean stepApplies(String stepFieldName) { if ("company".equals(stepFieldName)) { return account.accountType == AccountType.COMPANY; // skip for personal accounts } return true; } @WizardCompletionAction @Action(validationRequired = true) Object finish() { /* … */ return null; } } ``` `stepApplies` is evaluated on every render and navigation, so it can depend on values captured by any earlier step. When the skipped step was the penultimate one, the completion button moves to the last applicable step automatically. ## Layout modes — `@WizardLayout` By default a wizard shows one step at a time. Annotate the class with `@WizardLayout(...)` to change how it's laid out: ```java @WizardLayout(WizardLayoutMode.ACCUMULATIVE) public class OnboardingWizard extends Wizard { … } ``` | Mode | Behaviour | |---|---| | `STEPS` *(default)* | Only the current step is shown, one at a time. | | `ACCUMULATIVE` | The current step is editable, with a single compact **"Previous answers" recap card** above it — every completed step's values listed as dense `label: value` lines, grouped by step — so the user always sees what has been collected so far without it dominating the screen. | | `ACCORDION` | Every step is a **collapsible panel**: the current one is open and editable, completed ones are collapsed (expand to review), upcoming ones are disabled. As you advance, the previous panel collapses and the next opens. | <div style="display:flex; gap:1rem; flex-wrap:wrap;"> <figure style="flex:1; min-width:280px; margin:0;"> <img src="/images/docs/ux-patterns/wizard-accumulative.png" alt="Accumulative wizard — completed steps recapped above the current one" /> <figcaption><code>ACCUMULATIVE</code></figcaption> </figure> <figure style="flex:1; min-width:280px; margin:0;"> <img src="/images/docs/ux-patterns/wizard-accordion.png" alt="Accordion wizard — one collapsible panel per step" /> <figcaption><code>ACCORDION</code></figcaption> </figure> </div> Both non-default modes render previously entered data read-only; steps should use distinct field names (the wizard state is a single flat map across steps). ## Drafts, skipping and finishing early (the transactional guided process) Four affordances turn a wizard into a process the user can leave and come back to — the transactional half of the Redwood guided process. All of them are ordinary buttons composed on the server, so every renderer draws them with its own widgets. ```java @UI("/onboarding") @WizardProgress(WizardProgressStyle.STEPS) public class Onboarding extends Wizard implements Draftable { Contact contact = new Contact(); Preferences preferences = new Preferences(); Extras extras = new Extras(); Done done; // Draftable: "Save" and "Save and close" on every step @Override public Object saveDraft(HttpRequest rq) { drafts.save(this); return null; } @Override public Object closeDraft(HttpRequest rq) { return URI.create("/home"); } @Override public String resumeStep(HttpRequest rq) { return drafts.lastStepOf(rq); } // "Skip" on the optional steps @Override protected boolean stepSkippable(String step) { return "preferences".equals(step); } // cancelable hook before ANY move: null lets it happen, anything else is the answer @Override protected Object beforeStepNavigate(String from, String to, HttpRequest rq) { return "contact".equals(from) && contact.email.endsWith("@blocked.test") ? Message.error("That e-mail domain is not allowed") : null; } // offered beside Next from the preferences step on @WizardCompletionAction(availableFromStep = "preferences") @Label("Finish now") Object finish() { ... } } ``` | Piece | What it does | |---|---| | `Draftable.saveDraft(rq)` | "Save": the current step is hydrated but **not validated** (a draft may be incomplete); `null` answers "Draft saved" and the wizard stays put | | `Draftable.closeDraft(rq)` | where "Save and close" lands after saving (a `URI` or a `UICommand`; `null` = `/`); the page is marked clean first | | `Draftable.resumeStep(rq)` | the step (field name) a fresh load opens on — the one the user left | | `stepSkippable(step)` | "Skip": moves on without requiring that step's fields. Unlike `stepApplies`, the step is still there — the user chose to leave it for later | | `@WizardCompletionAction(availableFromStep = "…")` | the completion is offered beside Next from that step on | | `beforeStepNavigate(from, to, rq)` | runs before Next, Back, Skip, a jump to a visited step and the completion (whose `to` is the result step), after the step is hydrated and — going forward — its required fields checked. Return `null` to proceed; anything else cancels the move and is the response | ### Display options (`WizardDisplay`) Every built-in affordance of the wizard can be switched with the shared tri-state `Toggle` (`on` · `off` · `disabled` = shown but inert, which is what permissions need): ```java @Override protected WizardDisplay display() { return WizardDisplay.defaults().toBuilder() .saveDraft(canWrite ? Toggle.on : Toggle.disabled) .saveAndClose(Toggle.off) .build(); } ``` `saveDraft`, `saveAndClose` and `skip` default to `on` (each shows only where the wizard supports it). A `disabled` affordance is refused on the server too, not just greyed out. ## Structure ``` Account setup ← getTitle() [●────────────────────] Step 1 / 3 ← progress bar Account type: ○ Personal ● Business [Next →] ``` ``` Account setup [────●────────────────] Step 2 / 3 Company name: ___________ VAT number: ___________ [← Back] [Create account] ← @WizardCompletionAction ``` ``` Account setup [──────────────────────●] Done ✓ Account created successfully. ← no navigation buttons ``` ## Redwood parameter and slot reference What the Redwood `guided-process` template exposes, and what Mateu gives you for it. The gaps here are **the transactional ones** — drafts, resuming and skipping — which is the largest coherent piece of Redwood surface Mateu does not cover. The canonical page-header elements shared by every template are documented once in [Page templates](/ux-patterns/page-templates/). **Legend:** ✅ supported · 🟡 partial · — not supported · ⚪ deliberately out of scope | Redwood prop / slot | Mateu | | |---|---|---| | `processTitle` / `processSubtitle` | `getTitle()` / `@Title` | ✅ | | `steps[]` / `currentStep` | step fields; `numberOfSteps()`, `currentStepNumber()`, `getStep()` | ✅ | | `displayOptions.checklistDisplay: current \| all` | `@WizardProgress(BAR \| STEPS \| RAIL)` picks the progress presentation | ✅ | | Conditional steps | `stepApplies(stepFieldName)` — branching | ✅ | | Completion step | **Slot** `completionStep` ↔ `@WizardCompletionAction` + the done state | ✅ | | Validation before advancing | `validations()` runs before the step advances | ✅ | | `avatar` + `displayOptions.avatar` | `PageDto.avatar/icon` on the canonical header | 🟡 | | `primaryAction.availableFromStep` (enable the finish action from step N on) | `@WizardCompletionAction(availableFromStep = "…")` | ✅ | | `resumeStepId` (resume where the user left off) | `Draftable.resumeStep(rq)` | ✅ | | `displayOptions {save, saveAndClose}` + `spSave` / `spSaveAndClose` (drafts) | `Draftable.saveDraft` / `closeDraft` + `WizardDisplay.saveDraft` / `saveAndClose` | ✅ | | `spSkip {skippedStepId}` (user-initiated skip) | `stepSkippable(step)` + `WizardDisplay.skip` | ✅ | | `spBeforeNext` / `spBeforeStepNavigate` (cancelable hooks) | `beforeStepNavigate(from, to, rq)` | ✅ | | `completionStatus` / `continueWorkingStatus` | the done state is terminal | 🟡 | | `displayOptions.overviewAnimation` | — | — | | `displayOptions.density: standard \| compact` | `@Compact`, set on the view rather than as a template option | 🟡 | | **Slot** `announcement` (aria-live) | return `UICommand.announce(text)` / `announceAssertive(text)` from any action | ✅ | The related `step-by-step-page` template (a full-screen linear process) adds `timer {startTime, timeInterval}` for timed processes and `spFinishLater`; neither is built. For a wizard inside a drawer, see [Guided Process Drawer](/ux-patterns/drawer/#guided-process-drawer-a-wizard-in-a-drawer-embeddedview). ## Coverage | | Java | .NET | Python | Vaadin | Redwood | React Native | IntelliJ | |---|---|---|---|---|---|---|---| | Steps, branching, progress (BAR / STEPS / RAIL) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Drafts (`Draftable`: save, save and close, resume) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Skip (`stepSkippable`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Early completion (`availableFromStep`) | ✅ | 🟡 ¹ | ✅ | ✅ | ✅ | ✅ | ✅ | | `beforeStepNavigate` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `WizardDisplay` toggles | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | The renderer columns need no wizard-specific code: every affordance is a button composed on the server. ¹ The .NET and Python wizards number their steps (`[Step(n)]`), so the hooks take step numbers instead of field names, and .NET's early completion is the fixed `complete` action. ## Principles served - **Progressive complexity** — each step shows only what is needed at that moment - **Recoverability** — validation fires before advancing, not at the end - **Workflow over screens** — the wizard models a task, not an entity --- # Workspace URL: https://mateu.io/ux-patterns/workspace/ > A multi-panel environment where several related views coexist simultaneously. **Status:** Composition — no new primitive needed ## Intent A multi-panel environment where several related views coexist at once. ## Difference from Split View [Split View](/ux-patterns/split-view/) is two panels — master list and detail — for the same collection. A Workspace is the composition of several heterogeneous views on one screen: a queue, a detail, KPIs, a context panel. ## Problem Complex tasks require looking at several things simultaneously: an inbox plus a message detail, a queue plus a customer record, KPIs plus the underlying data. Resolving them by jumping between screens multiplies cognitive load. ## Solution :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Compose existing layout primitives. No new annotation is required. ```java @UI("/support") public class SupportWorkspace { @Section("Open tickets") private TicketQueue queue; // list component @Section("Ticket detail") private TicketDetail detail; // form component @Section("Customer context") private CustomerSummary context; // read-only summary } ``` Use `@MasterDetail` or a fluent `SplitLayout` for two-pane splits, `@Zones` for side-by-side arrangement, `@Tab` or `@FoldedLayout` to hide secondary panels until needed, and `@KPI` in a header row for live metrics. ## Structure ``` ┌─────────────┬──────────────────────┬──────────────┐ │ KPIs: 12 open · 3 urgent · SLA 94% │ ├─────────────┼──────────────────────┼──────────────┤ │ Inbox │ Ticket #4521 │ Customer │ │ ─────────── │ ──────────────────── │ ──────────── │ │ #4521 ● │ Subject: ... │ Acme Corp │ │ #4498 │ Priority: High │ Plan: Pro │ │ #4477 │ │ 3 open tix │ │ │ [Resolve] [Escalate] │ │ └─────────────┴──────────────────────┴──────────────┘ ``` ## Principles served - **Preserve context** — all relevant information is visible simultaneously - **Minimize navigation** — zero page transitions for related data - **Workflow over screens** — the screen is designed around the support task, not an entity --- # Reference URL: https://mateu.io/reference/ This section is the curated reference for Mateu's public DSL. The goal is not to duplicate the full Javadoc. The goal is to document the parts of Mateu that developers need to understand in order to use the framework effectively. Use this section when you want to answer questions like: - which annotation should I use? - what is the difference between declarative and fluent? - which interfaces define the extension points? - which public types are worth knowing? ## Sections - [Key annotations](/reference/key-annotations/) - [Key interfaces](/reference/key-interfaces/) - [Fluent model](/reference/fluent-model/) - [Useful types](/reference/useful-types/) - [Stability & versioning](/reference/stability-and-versioning/) — what is public API, deprecation and wire compatibility - [Migrating from alpha](/reference/migrating-from-alpha/) — every rename and removal of the 3.0 alphas - [Support policy](/reference/support-policy/) — which versions get fixes, supported Java/.NET/Python/IDE versions, SBOMs - [Known issues](/reference/known-issues/) — current limitations and their workarounds ## How to use this section - Use the manual to learn Mateu - Use this reference to confirm details - Use the Javadoc for the full API surface ## Related - [Java UI Definition](/java-ui-definition/) — full component, annotation and interface reference - [Java User Manual](/java-user-manual/start-here/quickstart/) — learn how to use Mateu step by step --- # Agent operability (MCP) URL: https://mateu.io/reference/agent-operability/ > Operate any Mateu app from an AI agent through an MCP server — the wire is self-describing, so every screen becomes a set of tools an agent can discover and run. Because a Mateu screen travels as a **self-describing wire model** (fields with types and validation, the actions available, navigation commands), it is not only something a renderer turns into pixels — it is something an **agent can operate**. A Mateu app is therefore a **second plane** on the same contract: the rendering plane (the web/native renderers) and the **agent-operability plane** — an [MCP](https://modelcontextprotocol.io) server that exposes each screen as tools any agent (Claude, Antigravity, an internal copilot) can discover and run. Think of it as **"a renderer of agents"**: same self-describing model, tools instead of pixels. The same server also lets an agent **author** screens: it serves the authoring contract (the schemas, a component catalogue, a guide) and tools to validate, preview and — in development mode — save a YAML definition. See [Authoring tools](#authoring-tools) and [Let an AI author screens via MCP](#let-an-ai-author-screens-via-mcp). And it can send UI to a UI that is open in a browser or an app — see [Drive a live UI](#drive-a-live-ui). For prompt-to-app without an MCP client, see [Prompt-to-app (AI authoring)](/reference/prompt-to-app/). ## The tools | Tool | What it does | |---|---| | `mateu_list_routes` | The navigable routes of the app (from its menu) → `[{route, caption}]`. | | `mateu_describe_screen` | Load a route → a flat screen: `title`, `fields` (id, label, dataType, required, value, options), `actions` (id, label), `listing` (if any), `state`. | | `mateu_run_action` | Run an action id (optionally seeding field values) → the resulting screen. | | `mateu_search` | Search a listing screen by free text (and optional filters). | The projection rules (how a `UIIncrementDto` becomes this flat screen) are **normative** and specified in [Wire specification → Agent operability](/reference/wire-specification/#agent-operability--the-mcp-projection), so every host produces the same result. ## Authoring tools Nothing here changes the running app — except `mateu_save_spec`, which exists only in development mode. | Tool | What it does | |---|---| | `mateu_list_components` | The component types a YAML definition can use, each with a one-line description and its main attribute names (`query` filters). | | `mateu_get_component_schema` | One type's JSON Schema plus every definition it references (enums, nested records) — what keys it takes and what values they accept. | | `mateu_validate_uidl` | Validate a definition (a page, an app shell or any `specs/ui` file kind) → `{valid, kind, errors, warnings}`. Each issue has a `code`, a `message`, a JSONPath and its `line`/`column`. | | `mateu_preview_uidl` | Validate, then render the page as the app would (layout only — no view model is bound) → `{rendered, screen, validation}`, `screen` being the same projection as `mateu_describe_screen`. | | `mateu_save_spec` | **Development mode only** (`mateu.dev=true` / `MATEU_DEV=true`; listed only then): validate and, with no errors, write the file into the specs directory; live reload shows it in the open browsers. | What validation reports: - **errors** — anything that makes the definition fail to load: YAML syntax, an unknown `type` (with a "did you mean"), a missing `type:` or required key, a value of the wrong type, a value outside its enum (e.g. `dataType: decimal`, which does not exist — use `number` or `money`), and finally whatever the app's real loader still refuses (`load_failed`), so "valid" never means "and then the page answers Not found"; - **warnings** — unknown keys (the loader ignores them, so it is usually a typo; the closest known key is suggested), button/trigger action ids that nothing declares on a page with no view model, and references that do not resolve in this app: `ref:` of a REST source, a `Partial`, a `ComponentRef`, a `fieldType`. Resources (`resources/list`, `resources/read`): | URI | Content | |---|---| | `mateu://guide` | A short authoring guide for agents: the workflow, a sample page, the rules. | | `mateu://catalog` | The component catalogue — generated from the schema, each component described by its own Javadoc. | | `mateu://schema/specs` | `specs-schema.json`: every file kind under `specs/ui`. | | `mateu://schema/uidl` | `uidl-schema.json`: the component catalogue as JSON Schema. | They ship inside the app (the `mateu-uidl` jar, the .NET assembly, the Python package, the sidecar), so an agent gets the contract of the version it talks to, without network access. ## Two hosts, one projection - **Sidecar** — `frontend/mcp-server/`, a zero-dependency Node MCP server. It speaks only the public wire, so it operates a **Java, .NET or Python** backend with **no backend change**. Point it at a URL and go. This is the quickest way to try it, and it covers **every** backend today. - **Native endpoint** — the backend serves the same MCP projection directly, so an app can *also be an MCP* with no sidecar to deploy, enforcing permissions natively. Available on **Java** (every adapter: Spring MVC, Spring WebFlux, Micronaut, Quarkus, Helidon MP), **Python** (FastAPI) and **.NET** (ASP.NET Core) — all at `POST /mateu/mcp`, all sharing one projection. It is **off by default** everywhere: enable it with `mateu.mcp.enabled=true` (Java), `MateuOptions.Mcp = true` (.NET), `add_mateu(..., mcp=True)` (Python), or the `MATEU_MCP_ENABLED=true` environment variable on any backend (on Java the framework's own configuration maps it to `mateu.mcp.enabled`, as Spring, Micronaut and MicroProfile Config do for any environment variable). It gives any caller holding a valid token a programmatic way to drive every screen, which the application has to decide to expose. ## Permissions (RBAC) Authorization is enforced by the **backend**, not by the MCP layer: `@EyesOnly`, `@ReadOnlyUnless` and `@DisabledUnless` are applied server-side over the caller's JWT. The MCP **inherits** that — it never opens a wider path. An action a token may not run **never reaches the wire**, so it never appears as a tool result. The sidecar simply relays a `MATEU_TOKEN` bearer to the backend. The authoring tools go through the same path: validation and preview run as reserved actions of the app (`__validate__`, `__preview__`), so the caller's identity and the route's `access:` rules apply, and a preview renders only the text it is given — no view model, no data. A refused call is the tool error `Error: Forbidden`; an unexpected failure is `Error: An unexpected error occurred. Reference: <id>` (logged under that id; the raw message only with `MATEU_ERRORS_DETAILED=true`). Definitions are capped at 256 KiB. `mateu_save_spec` refuses any path that is not a relative `.yaml`/`.yml` inside the specs directory (no `..`, no absolute path, no symbolic link out), and it saves only what a screen is made of — a page, a layout envelope, a partial or a business-component catalogue. Sources, environments, routes, actions, types, translations, mounts and project settings (and their conventional file names) are written by hand, and so is any page that references a `${secret.…}`, marks a request `proxy: true` or overrides the request of a source it names by `ref`: otherwise an agent in dev mode could re-point a proxied source at its own server and have Mateu send it the secret. Nor does it save a page that would run code in the browser — an `Element` with an `on…`, `import` or `srcdoc` attribute, an unsafe url, `html: true` or a script-capable element, a `javascript:` url, a `RunJS` rule, an action's `js`, a `MicroFrontend` loaded from another server: exactly what the untrusted strip takes out of a screen an agent pushes. A saved spec is served through the ordinary render path, which trusts the author, so writing one must not be a way around that strip. `__validate__`, which these tools are built on, is served only to MCP tool calls, or by an app with `mateu.mcp.enabled=true` or in dev mode. ## Use it from an agent Register the sidecar as an MCP server (stdio): ```jsonc { "mcpServers": { "mateu": { "command": "node", "args": ["frontend/mcp-server/index.mjs"], "env": { "MATEU_BASE_URL": "http://localhost:8080", "MATEU_TOKEN": "<optional bearer>" } } } } ``` Then an agent can, for example: `mateu_list_routes` → `mateu_describe_screen("bookings")` → read the fields and filters → `mateu_search("bookings", "smith")` → `mateu_run_action("bookings", "export")`. ## Let an AI author screens via MCP Run the app in development mode with the endpoint on, and register it with your agent. With Claude Code, against the native endpoint: ```bash # the app: mateu.mcp.enabled=true + mateu.dev=true (or MATEU_MCP_ENABLED=true MATEU_DEV=true) claude mcp add --transport http mateu http://localhost:8080/mateu/mcp ``` Or through the stdio sidecar, which works against any backend with the endpoint off; it saves into a local specs directory when `MATEU_DEV=true` (`MATEU_SPECS_DIR`, default `src/main/resources/specs/ui`): ```bash claude mcp add mateu --env MATEU_BASE_URL=http://localhost:8080 --env MATEU_DEV=true \ -- node frontend/mcp-server/index.mjs ``` Then ask for a screen ("a customer form with name, email and a Save button"). A good agent reads `mateu://guide`, looks types up with `mateu_list_components` / `mateu_get_component_schema`, iterates with `mateu_validate_uidl` until there are no errors, checks the result with `mateu_preview_uidl` and saves it with `mateu_save_spec` — and the open browser reloads with it. The protocol version advertised is `2024-11-05` (clients negotiate down to it); the endpoint is a stateless JSON POST. ## Drive a live UI An agent can also send UI to a UI that is **open** — a browser tab, the React Native app, the IntelliJ tool window: show a screen it authored, navigate the user somewhere, or dispatch an event the page reacts to. It is the MCP twin of the in-app chat's `render-screen` / `navigation-requested` events: the UI applies a pushed message exactly as it applies the chat's, through the same code. ### Enable it Off by default, and it needs the MCP endpoint on too: | Host | Switch | |---|---| | Java (every adapter) | `mateu.mcp.enabled=true` + `mateu.mcp.push.enabled=true` (or `MATEU_MCP_ENABLED` / `MATEU_MCP_PUSH_ENABLED`) | | .NET | `MateuOptions.Mcp = true` + `MateuOptions.McpPush = true` (or `MATEU_MCP_ENABLED` / `MATEU_MCP_PUSH_ENABLED`) | | Python | `add_mateu(..., mcp=True, mcp_push=True)` (or the same environment variables) | Limits: `mateu.mcp.push.rate-per-minute` (30 messages per session per minute), `mateu.mcp.push.max-sessions` (1000 registered sessions), `mateu.mcp.push.max-sessions-per-owner` (20 per signed-in user) and `mateu.mcp.push.max-anonymous-sessions-per-address` (200 anonymous UIs per client address; an address the server cannot tell is not limited); same names as `MATEU_MCP_PUSH_*` environment variables and as .NET (`MateuOptions.McpPush…`) / Python (`add_mateu(mcp_push_…)`) options. An anonymous UI counts on its own against the per-owner cap, so strangers sharing an address cannot lock each other out. **Behind a reverse proxy.** The client address is the one your framework resolves: the socket peer, unless you configured its forwarded-header handling with the proxies you trust — Spring `server.forward-headers-strategy=framework` (or `native`), Quarkus `quarkus.http.proxy.proxy-address-forwarding=true` with `quarkus.http.proxy.trusted-proxies`, Micronaut `micronaut.server.client-address-header`, ASP.NET Core `UseForwardedHeaders` with `KnownProxies`, uvicorn `--proxy-headers --forwarded-allow-ips=<proxy>`. Mateu never reads `X-Forwarded-For` itself (a header any client can set), and on Helidon MP it is always the socket peer. Without that configuration every anonymous UI shares the proxy's address, and the per-address limit applies to all of them together: configure the framework, or raise the limit. With it on, every app shell gets a **Connect AI** control in its header (a drawer row on React Native, a toolbar action in IntelliJ), and each UI keeps one small event stream open — its *agent channel*, the app-level `_agent-channel` action over the SSE endpoint every adapter already has. One channel per **tab**: a push is meant for the tab the user is looking at, not for every tab of the browser. ### Pair A signed-in user's own agent needs no pairing: an MCP caller authenticated as the same principal sees that user's sessions in `mateu_list_sessions`. Any other agent — a local Claude Code, the sidecar, an anonymous caller — must be **paired**: 1. the user clicks **Connect AI**; the UI shows a one-time code (`K7QF-4MZP`) with a countdown; 2. the user tells the agent the code; the agent calls `mateu_pair_session {code}`; 3. the UI shows "AI connected" and who; **Disconnect** removes the pairing at once. A code works once and dies after five minutes (or when a new one is asked for). ### The tools Listed only when push is on, after the operating and authoring tools: | Tool | What it does | |---|---| | `mateu_list_sessions` | The sessions this caller may reach (its own + paired): `{session, user, route, renderer, connectedAt, connected, paired}`. | | `mateu_pair_session` | Pair a session with the code its user sees. | | `mateu_push_ui` | Validate a YAML page (nothing is sent when it has errors), then show it in that tab: `target` = `content` (default), `drawer` or `dialog`, optional `title`. | | `mateu_navigate` | Navigate that tab to a route, like a menu click (`route`, plus the optional `consumedRoute`, `actionId`, `baseUrl`, `serverSideType`, `uriPrefix`). | | `mateu_dispatch_event` | Dispatch a named event (`@SubscribeTo` views take it). The built-in events are reserved for the two tools above. The tab delivers it only while a view on screen subscribes to it, and never a framework event name (see [the event catalogue](/ai/#the-event-catalogue)). | The pushed screen is rendered by the UI through the same reserved `__preview__` action as the chat's `render-screen`: layout only, no view model is created or bound, and it is requested **with the UI's own identity**, so the route guard and the wire-type policy apply again on the receiving side. Whatever the screen does afterwards — its buttons, its REST sources — goes through the same checks as any other request. ### Security model - **Off by default**, and only with the MCP endpoint on. - **Who may reach a session**: a caller signed in as the session's user, or a caller the session was **paired** to. The caller is its authenticated principal; else the `X-Mateu-Agent-Key` header (what the sidecar sends, ≥ 16 characters); else anonymous — and an anonymous caller only reaches a session it paired, by the opaque handle the pairing answered. Anything else answers `Unknown session` — a session of another user and one that does not exist look the same. - **The UI side is pinned**: a session belongs to the secret its tab generated and to the principal it registered with; another tab, user or guess cannot take over its stream or ask for its codes. - **Limits**: 30 messages per session per minute, 256 KiB per screen, 64 KiB per event detail, 10 failed pairings per minute per caller and per client address (rotating the agent key does not buy more guesses, and anonymous callers elsewhere are not locked out), 1000 sessions and 20 per owner (a user, or an anonymous UI's client address — so one caller cannot fill the registry); a disconnected session is forgotten two minutes after its stream ended. - **Audit**: every delivery is logged at INFO — `Mateu agent push: caller=<who> session=<fingerprint> kind=<render|navigate|event> … bytes=<n>` — and every pairing too. The session is named by its fingerprint (`s-` + the first 12 hex digits of the handle's SHA-256, the same in Java, .NET and Python), never by its handle: the handle is what reaches the session, so it must not sit in a log. - In-process: in a cluster, the stream and the MCP call must reach the same node (sticky sessions). ### Example with Claude Code ```bash # the app: mateu.mcp.enabled=true + mateu.mcp.push.enabled=true claude mcp add --transport http mateu http://localhost:8080/mateu/mcp # or through the sidecar (it forwards the push tools to the app's /mateu/mcp) claude mcp add mateu --env MATEU_BASE_URL=http://localhost:8080 --env MATEU_PUSH=true \ -- node frontend/mcp-server/index.mjs ``` Open the app, click **Connect AI**, and tell Claude: *"pair with K7QF-4MZP and show me a check-in form for Nora Duarte in a drawer"*. It calls `mateu_pair_session`, writes the page (checking it with `mateu_validate_uidl`), and `mateu_push_ui` puts it in front of you; *"now take me to her booking"* is a `mateu_navigate`. The wire is specified in [Wire specification → Live UI push](/reference/wire-specification/#live-ui-push) and pinned, with the security rules, by `conformance/mcp/push.json`. ## The in-app assistant uses the same projection The built-in AI chat (`@AI(sse=…)`) is the *other* face of the same idea. With every message it now sends a **self-describing projection of the screen the user is looking at** — the same shape the MCP produces: the current fields (id, label, dataType, value) and the actions available. So the assistant fills forms and runs actions precisely instead of guessing from raw state, and it drives the UI by returning the wire events every renderer applies (`navigation-requested`, `render-screen` — a screen it authored, rendered by the page that subscribes to it or else by the shell —, dispatched events…; see the [event catalogue](/ai/#the-event-catalogue)). One projection, two consumers: external agents (MCP) and the in-app assistant. ## Verify ```bash cd frontend/mcp-server && npm test # projection (against the conformance corpus) + protocol MATEU_BASE_URL=http://localhost:8080 node e2e/mcp-probe.mjs # end-to-end against a live backend MATEU_BASE_URL=http://localhost:8080 node e2e/mcp-probe.mjs --native # the app's own /mateu/mcp ``` See `frontend/mcp-server/README.md` for the full tool surface and configuration. --- # Fluent model URL: https://mateu.io/reference/fluent-model/ Mateu is not only declarative. It also provides a fluent model made of records and interfaces that implement `Component`. This model lets you build pages, apps and reusable UI blocks programmatically. --- ## Core fluent types ### `App` Represents an application shell. Important fields include: - route - homeRoute - pageTitle - title - subtitle - menu - widgets - variant - logo `App` is the fluent equivalent of a full application shell. --- ### `Page` Represents a full page with: - title - subtitle - breadcrumbs - header - footer - content - toolbar - buttons - badges - kpis - actions Use it when you want explicit control over a page structure. --- ### `Form` Represents a fluent form with: - header - footer - content - toolbar - buttons Use it when you want form composition without relying only on inferred declarative fields. --- ### `Listing` Represents a listing/table/card-style collection page. Important capabilities include: - columns - filters - toolbar - search - selection - paging - lazy loading - detail path - header/footer content Use it for searchable collections and listing screens. --- ### `MenuBar` Represents a fluent menu bar built from `Actionable` options. Use it when navigation must be created explicitly. --- ## Action model ### `Action` Fluent representation of action behavior. It includes settings for: - background - validationRequired - confirmationRequired - rowsSelectedRequired - href - js - sse - modal config - custom events This matches the same conceptual space as the declarative `@Action`. --- ## Trigger model Mateu also exposes a fluent trigger model. Core types include: - `Trigger` - `OnLoadTrigger` - `OnSuccessTrigger` - `OnErrorTrigger` - `OnValueChangeTrigger` - `OnCustomEventTrigger` Use the fluent trigger model when dynamic interaction behavior should be described directly in code instead of only via annotations. --- ## UI metadata ### `UI` Small fluent metadata object with: - `favicon` - `pageTitle` - `homeRoute` Useful in combination with `UISupplier`. --- ## Mental model The fluent model gives you: - explicit component trees - explicit page composition - explicit app composition - a way to mix reusable UI blocks into declarative screens Use declarative by default. Use fluent when you need more control. --- # Java imports URL: https://mateu.io/reference/java-imports/ > Which package each sample's types come from, and why wildcard imports of io.mateu.uidl packages break with "reference is ambiguous". The Java samples in these docs leave the `import` lines out to stay short. They compile with **single-type imports** — one `import io.mateu.uidl.annotations.Menu;` per type — and your IDE adds those for you. They do **not** compile with wildcard imports of two Mateu packages at once: ```java import io.mateu.uidl.annotations.*; import io.mateu.uidl.data.*; // ← `Menu`, `Button`, `Text`… now exist twice public class Shell { @Menu Products products; // error: reference to Menu is ambiguous } ``` The reason is deliberate: an **annotation** and the **data record** it stands for share a name (`@Button` on a method vs a fluent `Button` you put in a component tree). If you prefer wildcards, import one package with a wildcard and the clashing types from the other one by name — a single-type import wins over a wildcard. ## Names that exist in more than one package | Simple name | Where | Which one a sample means | |---|---|---| | `Action` | `annotations`, `fluent` | `@Action` on a method → `annotations`; an `Action` in `actions()` → `fluent` | | `App` | `annotations`, `interfaces` | `@App(...)` on the shell class → `annotations` | | `Avatar`, `Badge`, `Breadcrumb`, `Breadcrumbs`, `BulletedList`, `Details`, `Icon`, `KPI`, `Notice`, `Status`, `Tab`, `Text`, `Tooltip` | `annotations`, `data` | on a field → `annotations`; built with `new`/`.builder()` in a component tree → `data` | | `Button`, `Menu`, `FormLayout`, `RestAction`, `Rule`, `Validation` | `annotations`, `data` | same rule: annotation vs record | | `Filterable`, `Searchable` | `annotations`, `interfaces` | `implements Filterable<F>` / `Searchable` on a listing → `interfaces`; `@Searchable` on a lookup field → `annotations` | | `Listing` | `fluent`, `interfaces` | `implements Listing<Row>` → `interfaces`; a fluent listing component → `fluent` | | `Page` | `data`, `interfaces` | `Page<T>` returned by `CrudStore.find` → `data` | | `Step` | `data`, `fluent` | a flow step returned by an action → `fluent` | | `Trigger` | `annotations`, `fluent` | `@Trigger` on a class → `annotations`; a trigger in `triggers()` → `fluent` | | `UI` | `annotations`, `fluent` | `@UI("/route")` → `annotations` | All packages above are under `io.mateu.uidl`. ## Names that clash with the JDK | Mateu type | Clashes with | Tip | |---|---|---| | `io.mateu.uidl.annotations.List` | `java.util.List` | import `java.util.List` by name; the annotation is rarely needed | | `io.mateu.uidl.data.Map` (the map component) | `java.util.Map` | refer to one of them by its full name | | `io.mateu.uidl.data.Image` | `java.awt.Image` | only matters if you also import `java.awt.*` | --- # Key annotations URL: https://mateu.io/reference/key-annotations/ These are the annotations that define most of the Mateu DSL. This page is intentionally selective: it focuses on the annotations that shape routing, UI structure, actions, relationships, behavior, security, and presentation. --- ## `@UI` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Defines a UI root. ```java @UI("/products") public class Products {} ``` Use it when a class should become a page or UI entry point. ### Key fields - `value()` → route or UI path - `indexHtmlPath()` → frontend entry html - `frontendComponentPath()` → renderer entry path --- ## Inner routes (`routes.yaml`) `@Route`, `@Routes` and `@HomeRoute` were **removed**: `@UI` is the only routing annotation. The screens inside a UI — including routes with placeholders — are declared as data in a [`routes.yaml` route registry](/concepts/routes-and-mounts/). ```java public class ExamplePage { String name; // filled from :name } ``` ```yaml # src/main/resources/specs/ui/routes.yaml type: Routes routes: - route: example/:name viewModel: com.example.ExamplePage ``` Use a route entry when: - you need path parameters - you want more than one route over one class - you want nested routing (`children:` render in the parent's slot) --- ## `@Menu` Adds a field to the application menu. ```java @Menu Users users; ``` Use it to expose pages, modules or links in app navigation. ### Key fields - `selected()` → mark current option as selected --- ## `@Button` Marks a field or method as a button/action. ```java @Button void save() {} ``` Use it for form-level actions. Targets: - methods - fields --- ## `@Toolbar` Places a field or method in the toolbar. ```java @Toolbar void refresh() {} ``` Use it for top-level actions, typically in headers or listings. --- ## `@Action` Configures action behavior. ```java @Action( validationRequired = true, confirmationRequired = true ) ``` Use it when you need more than a bare button. `@Action` does **not** put a button on screen: it declares how an action behaves. The button comes from `@Toolbar` or `@Button` on the same method (or a `Button` with that `actionId`); on its own, an `@Action` method is still callable — by a keyboard `shortcut`, a trigger or a button supplied in code — but nothing is drawn for it. An action that returns a `String` (or any plain value) shows it as a message and leaves the screen as it was — there is no need to wrap it as `List.of(new Message(text), new State(this))`. ### What it controls - validation - confirmation dialogs - background execution - SSE - browser integration (`href`, `js`) - modal settings - selected-row requirement - fields to validate - how the CLIENT calls the action: `timeoutMillis` and `idempotent` ### Behaviour on a slow or unreliable connection ```java // A lookup the user is waiting on: give up quickly so they can retype. @Action(timeoutMillis = 5000) public void quickLookup() { … } // Batch work: a long ceiling, and safe for the client to re-send after a blip. @Action(timeoutMillis = 120000, idempotent = true) public Message recalculateTotals() { … } ``` - `timeoutMillis` — request ceiling for this action in ms. `0` (the default) keeps the client's own 60 s ceiling. One global timeout cannot serve both a type-ahead lookup and a report export. - `idempotent` — declares that re-running the action cannot apply the same change twice, so the client may retry it by itself after a transient failure. Defaults to `false`: after a timeout the client cannot know whether the server processed the request, so writes are never repeated behind the user's back. Reads (route loads, searches, lookups) are detected automatically. See [Slow connections](/ux-patterns/slow-connections/) for everything the framework does on a bad network without any declaration. --- ## `@Lookup` Defines a relationship resolved dynamically by backend suppliers. ```java @Lookup( search = PermissionOptionsSupplier.class, label = PermissionLabelSupplier.class ) List<String> permissions; ``` Use it when a field depends on remote or dynamic options. ### Key fields - `search()` → `LookupOptionsSupplier` - `label()` → `LookupLabelSupplier` --- ## `@Searchable` Adds a "Search" button to a field. Clicking it opens a modal containing the `selector()` class — typically a `Listing` that also implements `Selector`. When the user selects a row, the modal closes and the field is populated with the chosen id; `label()` resolves the display text for a stored id. ```java @Searchable(selector = HotelSelector.class, label = HotelSelector.class) String hotelId; ``` Use it when picking the related entity requires a filterable grid, row actions, or CRUD capabilities — anything beyond a simple dropdown (see `@Lookup`). ### Key fields - `selector()` → `Selector` implementation (usually a `Listing` subclass) opened in the modal - `label()` → `LookupLabelSupplier` to display the stored id as text - `editableCode()` → allow the user to type the id directly - `showCode()` → show the raw id alongside the label --- ## `@Stereotype` Overrides the default inferred rendering type of a field. ```java @Stereotype(FieldStereotype.radio) Status status; ``` Use it when the Java type is not enough to express how the field should be rendered. --- ## `@UseRadioButtons` Renders an enum field as radio buttons instead of the default dropdown, regardless of how many constants the enum has. Equivalent to `@Stereotype(FieldStereotype.radio)`, but self-documenting on the field. ```java @UseRadioButtons Weekday deliveryDay; ``` > Under [`@AutoLayout`](#autolayout), enums with up to 4 constants get radio buttons automatically — > use `@UseRadioButtons` to force them on larger enums or on classes without inference. --- ## `@AutoLayout` Lets Mateu **infer the UX patterns** of a form from the amount and structure of the declared information, so the class only declares the data and Mateu decides how to present it. Inference is deterministic (based on the declared structure, never on runtime data) and only fills the gaps the developer left open — every explicit layout annotation (`@Section`, `@Tab`, `@Zones`, `@FoldedLayout`, `@Toc`, `@Stereotype`, `@UseRadioButtons`…) always wins. ```java @UI("/customers/new") @AutoLayout public class NewCustomerForm { ... } // just declare the fields ``` Current rules: - **Fold optionals** — a heavy editable form with no declared grouping keeps its required fields visible and collapses the optional ones into a "More options" panel. - **Sections → tabs** — a read-only view with many substantial sections is presented as tabs (marked `adaptable`, so renderers may degrade them to an accordion on narrow viewports); a sticky section or an explicit `@Toc` disables this. - **Small enums → radio buttons** — enums with up to 4 constants render as radios. ### Key fields - `value()` — `@AutoLayout(false)` opts a class out when inference is enabled globally via the `mateu.layout.inference.enabled` setting (formerly `mateu.layout.inference`, still accepted). See [Layout inference](/ux-patterns/layout-inference/) for the full rules, thresholds and wire semantics. --- ## `@OnRowSelected` Binds row selection of a grid field (a `List` field rendered with `@Stereotype(FieldStereotype.grid)`) to a developer action. When the user clicks a row, Mateu runs the named method on the class that declares the grid field, **auto-injecting the selected row** as a method parameter (the parameter typed as the row class, via `HttpRequest.getClickedRow`). Unlike the built-in CRUD detail editing, it works on read-only grids too — making it the natural way to build a master/detail view: select a row, then emit an event or update another part of the screen. ```java @OnRowSelected("onGuestSelected") @Stereotype(FieldStereotype.grid) List<GuestData> guests; Object onGuestSelected(GuestData guest, HttpRequest httpRequest) { return UICommand.dispatchEvent("pax-selected", Map.of("name", guest.getFirstName())); } ``` ### Key fields - `value` — name of the method/action to run when a row is selected. - `shortcut` — optional keyboard-shortcut base (e.g. `"ctrl+shift"`) for selecting a row by position: the base combo plus a digit selects that row (`ctrl+shift+1` → first row … ninth; top-row or numeric keypad). > Combine with [`@SubscribeTo` / `@Emits`](#subscribeto) to drive other components from a selection. > Opt-in: grids without `@OnRowSelected` keep their default selection behaviour. --- ## `@Style` Adds inline CSS style to a type, field or parameter. ```java @Style("max-width:900px;margin:auto;") ``` Use it for layout constraints and small visual adjustments. --- ## `@StaticView` Class-level. Declares a view whose **full response — structure and data — never varies** per request, user or time (a help page, an "about" screen, a fixed reference screen). The client caches the whole response for the browser session and, on a return visit, renders it from the cache and **skips the server round-trip entirely**. ```java @Title("About") @StaticView public class About { /* ... */ } // routed by a routes.yaml entry (route: about) ``` It is a promise, like `@Action(idempotent = true)`: only use it when the content genuinely does not change. Do **not** use it on a screen whose content depends on data, the logged-in user, permissions, time, or `${…}` interpolation of live state — the client would keep showing the first rendering for the rest of the session. The skip is session-scoped, so a full page reload always reloads (a new deployment is picked up on the next refresh). This is the opt-in top layer of Mateu's [client-side caching](/ux-patterns/client-side-caching/); the two layers beneath it (instant structure on return, and smaller data-only revalidation) are automatic and need no annotation. Also available as `[StaticView]` (C#) and `@static_view` (Python). --- ## `@FormLayout` Controls form rendering. ```java @FormLayout(columns = 1) public class MixedPage {} ``` Use it when you want to change the default form layout. ### Key fields - `columns()` — default 2 - `labelsAside()` — `LabelsAsideMode.AUTO` (default: infer), `ASIDE` (labels left of the fields) or `TOP` (labels above) — see [labels on top vs labels aside](/java-ui-definition/forms/#labels-on-top-vs-labels-aside) - `theme()` - `style()` --- ## `@Rule` Defines dynamic browser-side behavior. ```java @Rule( filter = "state.name == null || state.name == ''", action = RuleAction.SetAttributeValue, fieldName = "save", fieldAttribute = RuleFieldAttribute.disabled, value = "true", expression = "", actionId = "", result = RuleResult.Continue ) ``` `RuleAction` values: `SetAttributeValue`, `SetStateValue`, `SetDataValue`, `SetAppStateValue`, `SetAppDataValue`, `SetCssClass`, `SetStyle`, `RunAction`, `RunJS`. `RuleResult` is `Continue` or `Stop` (stop evaluating further rules once this one matches). Use it when the UI must change dynamically without a server round-trip. ### What it can affect - field attributes - values - styles - css classes - actions --- ## `@Trigger` Defines when an action runs. ```java @Trigger(type = TriggerType.OnLoad, actionId = "refresh") ``` Use it when an action should be triggered automatically. ### Trigger types - `OnLoad` - `OnSuccess` - `OnError` - `OnValueChange` - `OnCustomEvent` --- ## `@SubscribeTo` Subscribes a component to a named custom event emitted by another component (or itself), so components on the same screen can talk to each other. When the event fires, Mateu runs the named action on the subscribing component server-side, passing the event payload as the action parameters. Repeatable at class level. ```java // React to any "checkin-confirmed" event on the global bus by re-running this component's load. @SubscribeTo(event = "checkin-confirmed", action = "load") public class CheckInForm { ... } ``` Use it together with [`UICommand.dispatchEvent(...)`](#emitting-events) — one component emits, others react and refresh in place instead of forcing a full navigation. ### Key fields - `event` — name of the custom event to listen for. - `action` — id (method name) of the action to run when the event fires. - `source` — where to listen (`SubscriptionSource`): - `DOCUMENT` (default) — global event bus: react no matter which component emitted the event. - `COMPONENT` — react only to events emitted by the component named in `from`. - `SELF` — react only to events bubbling up from this component's own subtree (the behaviour of a raw `@Trigger(type = OnCustomEvent)`). - `from` — logical name of the emitting component to match, used only with `source = COMPONENT` (matches the emitter's `@Emits(name = ...)`). - `condition` — optional client-side expression that must hold for the action to run. > A raw `@Trigger(type = OnCustomEvent, ...)` is equivalent to `@SubscribeTo` with `source = SELF`. --- ## `@Emits` Declares the custom events a component emits and, optionally, the logical name it emits them under. It is mostly documentary — events are actually emitted by returning `UICommand.dispatchEvent(...)` from an action. Its one runtime effect is `name`: when set, it is stamped into every event the component emits (as `detail.__source`) so `@SubscribeTo(source = COMPONENT, from = ...)` subscribers can filter by origin. When omitted, the component's server-side type acts as the implicit source. ```java @Emits(events = "checkin-confirmed", name = "guests-section") public class GuestsSection { ... } ``` ### Key fields - `events` — names of the events this component emits (documentary). - `name` — logical source name stamped into emitted events as `detail.__source`. ### Emitting events Return a `UICommand.dispatchEvent(...)` from any action to fire a custom event from that component: ```java @Toolbar Object confirmCheckin(HttpRequest httpRequest) { // ... persist ... return List.of( Message.success("Check-in confirmed"), UICommand.dispatchEvent("checkin-confirmed", Map.of("reservationId", id))); } ``` The event bubbles (`composed`), so `DOCUMENT`-scoped subscribers anywhere on the page receive it. --- ## `@EyesOnly` Restricts access to parts of the UI. ```java @EyesOnly(roles = "admin") @Menu Users users; ``` Use it for authorization. It gates **menu entries** and, on a **form field**, hides the field when the current user is not authorized. Mateu does not authenticate: the identity is the one your host framework authenticated (Spring Security, Quarkus, Micronaut, JAX-RS), or what a `PrincipalResolver` bean of yours returns — never a Bearer token's payload, which Mateu does not decode. No identity → every restricted element is denied. See [How authorization works](/java-user-manual/advanced/security/#how-authorization-works). ### Supported scopes - roles - groups - scopes - permissions The same four dimensions are used by `@ReadOnlyUnless` and `@DisabledUnless` below. Matching is AND across the dimensions you declare, OR within each; no dimension declared → unrestricted. ### Enforced on write, not just on render The browser is untrusted, so these restrictions are not merely visual. On every request, when Mateu hydrates the ViewModel from the incoming component state, it **drops** any state entry targeting a field whose `@EyesOnly` or `@ReadOnlyUnless` restriction the request does not satisfy — a tampered component state cannot write a field the UI hides or locks (the Mateu equivalent of mass-assignment protection). The field keeps its server-side value instead. Consequence: never rely on the round-tripped state for a protected field's value — compute it server-side (initializer, `load()`, or the action itself). For an unauthorized user the client copy is never read back. --- ## `@ReadOnlyUnless` Renders a field (or, at class level, the whole view) **read-only unless** the current user matches one of the declared identity dimensions — same dimensions and matching as `@EyesOnly`. ```java @ReadOnlyUnless(roles = "manager") BigDecimal salary; // read-only for everyone except managers ``` Composes with `@EyesOnly` for layered access: ```java @EyesOnly(roles = "staff") // hidden unless staff @ReadOnlyUnless(roles = "manager") // read-only unless manager BigDecimal salary; // non-staff: hidden · staff: read-only · manager: editable ``` --- ## `@DisabledUnless` Renders a field or a button (`@Button` / `@Toolbar`) **disabled unless** the current user matches one of the declared identity dimensions — same dimensions and matching as `@EyesOnly`. Disabled state is carried as a client-side rule; the authorization is decided server-side. ```java @DisabledUnless(scopes = "write") String note; @Toolbar @DisabledUnless(roles = "approver") Object approve(HttpRequest req) { ... } ``` --- ## `@KeycloakSecured` (deprecated) Secures a UI using Keycloak. **Deprecated in 3.0-alpha.412**: identity comes from your host framework or a `PrincipalResolver` — see [Security](/java-user-manual/advanced/security/). It keeps working. ```java @UI("") @KeycloakSecured( url = "https://auth-server", realm = "mateu", clientId = "demo" ) public class App {} ``` Prefer your framework's authentication for new apps. ### Key fields - `url()` - `realm()` - `clientId()` - `jsUrl()` --- ## `@SplitCrud` Switches a `Crud` (or `AutoCrud`) to a split-panel layout: the record list stays on the left and the create/edit form opens on the right. No page transition occurs when the user selects a row. ```java @UI("/orders") @SplitCrud public class OrdersCrud extends AutoCrud<Order> { @Override public CrudStore<Order> store() { return new OrderStore(); // your CrudStore<Order> } } ``` The framework hides the *Cancel* button in the create form and automatically refreshes the list after saving. See [Split View](/ux-patterns/split-view/) for the full behaviour. --- ## `@ReadOnly` Applied to an `AutoCrud`, `FilteredAutoCrud`, or `Crud` class, hides the New, Edit, and Delete buttons. Shorthand for applying `@NotCreatable @NotEditable @NotDeletable` together. ```java @UI("/audit-log") @ReadOnly public class AuditLog extends AutoCrud<LogEntry> { ... } ``` Applied to a field or an `EditableView` class, makes that field or the entire view non-editable. --- ## `@NotNavigable` Applied to a `Crud` class. Hides the View button column in the listing — rows are not clickable and do not navigate to the detail screen. ```java @UI("/products") @NotNavigable public class ProductList extends AutoCrud<Product> { ... } ``` Combine with `@ReadOnly` for a plain read-only list with no detail view: ```java @ReadOnly @NotNavigable public class AuditLog extends AutoCrud<LogEntry> { ... } ``` --- ## `@NotCreatable` Applied to a `Crud` class. Hides the New button in the listing toolbar. ```java @NotCreatable public class OrderLines extends AutoCrud<OrderLine> { ... } ``` --- ## `@NotEditable` Applied to a `Crud` class. Hides the Edit button in the detail view toolbar. ```java @NotEditable public class ArchivedOrders extends AutoCrud<Order> { ... } ``` --- ## `@NotDeletable` Applied to a `Crud` class. Hides the Delete button in the listing toolbar. ```java @NotDeletable public class Invoices extends AutoCrud<Invoice> { ... } ``` --- ## `@ConfirmOnNavigationIfDirty` Enables dirty-state tracking on a form. When the user modifies any field, the frontend shows a confirmation dialog if they try to navigate away before saving. ```java @ConfirmOnNavigationIfDirty public class MyForm { String name; @Toolbar Object save() { // persist ... return UICommand.markAsClean(); // clear dirty flag after save } } ``` Tracking is **opt-in**: a plain page without this annotation never prompts on exit, even if it has editable fields and a `save()` action. CRUD create and edit views are the only exception — they activate the behaviour automatically, so the annotation is only needed on standalone forms. The confirmation covers every way of leaving the form: in-app menu navigation, the browser back/forward buttons, reloading or closing the tab, and the form's own leave actions — `cancel`, `cancel-…` (the CRUD's Cancel and Back to list), `back` and `backToList` — which ask before they run and send nothing if the user stays. A wizard's Back moves between steps of the same screen, so it never asks. Use `UICommand.markAsClean()` in save actions and `UICommand.markAsDirty()` to set the flag programmatically. --- ## Other useful annotations These are also part of the public DSL and are worth knowing: - `@Label` — set the display label of a field or button (instead of deriving it from the name) - `@Help` — help/hint text on a class, field, or method - `@LinkTo` — navigation icon at the right of a field pointing to a URL or route; the href supports `${state.…}` templates interpolated live in the browser, so `@LinkTo("/customers/${state.customerId}")` follows the value as the user types (optional `icon`, `title`, `target`; for runtime decisions implement `LinkSupplier`) - `@Validation` — declarative cross-field validation (`condition`, `fieldId`, `message`; repeatable) - `@Multiline` — let a `@PlainText` value wrap across multiple lines - `@Text` — render a String field as a text block (`container` picks the HTML element; `size` = `xl`/`l`/`m`/`s`/`xs` scales the font; `noMargins = true` drops the block margins) - `@BulletedList` — render a `List<String>` field as a plain bulleted list (`<ul>`); fluent counterpart `BulletedList` - `@SeparatorBefore` — paint a full-width divider line (`<hr>`) above the field; fluent counterpart `Separator` - `@Notice` — render a String field as a compact inline banner (see [Notice](/ux-patterns/notice/)); a blank value hides it - `@UploadableImage` — image field with upload/replace/delete, stored as data URI or URL - `@Signature` — signature capture on a String field (drawing canvas → PNG data URI in the value) - `@PhotoCapture` — photo capture on a String field (device camera → JPEG data URI; file-input fallback opens the native camera on phones) - `@TreeSelect` — the field's dropdown unfolds a TREE of options (children come from the view's `OptionsSupplier`); `leavesOnly = true` restricts selection to leaves - `@MainFilter` / `@Filterable` — mark filter fields for CRUD listings - `@RangeFilter` — render a numeric field's listing filter as a min–max range (temporal fields are ranges by default); the bounds travel as `<field>_from`/`<field>_to` and reach the store (`CrudStore`) as a `FilterCriterion` - Home route — `@HomeRoute` was removed: the home is the app's first menu item, or what the app class returns from `HomeRouteSupplier.homeRoute()` - `@Fab` — floating action button (app level or page level) - `@AppContext` — application-level context selector on the app header (active hotel, company…); options from an enum or a `LookupOptionsSupplier`, value readable everywhere via `httpRequest.appContext(fieldName)` - `@KPI` — render a numeric field as a dashboard KPI card - `@WizardCompletionAction` — the method that completes a `Wizard` (shown on the penultimate step) - `@WizardProgress` — the wizard's progress style: `BAR` (default), `STEPS` (connected step bullets) or `RAIL` (sticky lateral band: `current | total` counter over the vertical step list) - `@WizardLabels(back = …, next = …)` — the labels of the wizard's built-in Back / Next buttons (default "Back" / "Next", translated through the app's `Translator`) - `@AutoSave` - `@Icon` - `@PageTitle` - `@Title` - `@Subtitle` - `@Logo` - `@FavIcon` - `@Widget` - `@Footer` - `@Header` - `@Section` (incl. `zone` for use with `@Zones`, `sticky = true` to pin the section card, `propertyList = true` to render every field as a read-only label-left/value-right row with dividers, and `frameless = true` to drop the section card and its padding) - `@Zones` / `@Zone` — side-by-side layout zones (columns of sections); columns stack vertically when they don't fit (responsive) - `@Toc` — sticky sections index (table of contents) on a long page; see [Sticky sections index](/ux-patterns/sections-index/) - `@Compact` — high-density page preset (`StyleConstants.COMPACT`) - `@PlainText` — render a value as read-only text instead of an input - `@ColumnWidth` — grid column width; a fixed value (`"9rem"`) or `"auto"` (size to content) - `@InlineEditing` — edit a list/grid field's rows in place (editable cells) instead of a detail form - `@Colspan` — how many form columns the field spans. Intrinsically wide fields (grids, textareas, rich text, html, markdown) auto-span the full row in a multi-column section, on a row of their own; an explicit `@Colspan` greater than 1 wins over the automatic rule - `@HiddenInList` - `@HiddenInView` - `@HiddenInEditor` - `@HiddenInCreate` - `@EditableOnlyWhenCreating` - `@Status` - `@Representation` - `@Details` - `@Tab` — group fields into a tab (`value` = label; `shortcut` = keyboard shortcut to select it; `open = true` makes it the tab selected on first render instead of the first-declared one); see [Keyboard shortcuts](/ux-patterns/keyboard-shortcuts/) ## Mental model The Mateu DSL is annotation-heavy by design. Annotations define: - routing - structure - behavior - relationships - rendering - security The result is a declarative application model instead of a separate frontend implementation. --- # Key interfaces URL: https://mateu.io/reference/key-interfaces/ These interfaces define the most important extension points in Mateu's public DSL. --- ## `Component` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The base interface for fluent UI components. ```java public interface Component { default Map<String, String> attributes() { ... } default Map<String, Object> properties() { ... } default String style() { ... } default String cssClasses() { ... } } ``` Any type implementing `io.mateu.uidl.fluent.Component` can be embedded in fluent UIs and also inside declarative pages. This is one of the key bridges between declarative and fluent Mateu. --- ## `ComponentTreeSupplier` Use this when a class should return its UI explicitly instead of being inferred declaratively. Use it for: - custom pages - advanced composition - full fluent UIs --- ## `ContentSupplier` Marks a type that exposes child components through `content()`. Used in layout-like and container-like components. --- ## `ActionSupplier` Marks a type that exposes executable actions through `actions(HttpRequest)` (a `default` method returning `List<Action>`). Useful in page-like components such as the fluent `Page`. --- ## `TriggersSupplier` Marks a type that provides a list of triggers dynamically from the request context. Use it when triggers should not be static. --- ## `AppSupplier` Specialized extension point for classes that return a fluent `AppShell`. ```java public interface AppSupplier extends ComponentTreeSupplier { AppShell getApp(HttpRequest httpRequest); } ``` Use it when the whole application shell is produced fluently. --- ## `UISupplier` Provides fluent UI metadata. ```java public interface UISupplier { UI getUI(HttpRequest httpRequest); } ``` Useful when page metadata should be generated programmatically. --- ## `CrudStore` This is one of the central interfaces for CRUD-oriented Mateu applications. Use it when Mateu should read, save, list, and delete entities through a data-access store abstraction. Typical responsibilities: - `findById` - `save` - `findAll` - `deleteAllById` - `find(searchText, filters, pageable)` — search + filter + sort + paginate, returning `Page<T>`. Has a default in-memory implementation over `findAll()`; override it for database-side paging. --- ## `LookupOptionsSupplier` Defines how a lookup field searches available options. Use it with `@Lookup`. In real applications, this is usually a bean in your DI container (Spring, Micronaut, Quarkus, Helidon MP…) so it can inject repositories, services, or API clients. Typical use cases: - remote relationships - searchable dropdowns - large datasets - pageable option lists --- ## `LookupLabelSupplier` Defines how Mateu resolves the display label for a selected id/value. Use it with `@Lookup` or `@Searchable` when the raw value is not enough for UI rendering. In real applications, this is usually a bean in your DI container (Spring, Micronaut, Quarkus, Helidon MP…). --- ## `LabelSupplier` Provides field label text dynamically at request time, overriding any `@Label` annotation on the field. Return `null` or an empty string to fall back to the annotation or the humanized field name. Use it when field labels depend on runtime state (e.g., the same field shows different labels depending on the value of another field). --- ## `LinkSupplier` Attaches a navigation icon to the right side of form fields at request time, taking precedence over any `@LinkTo` annotation. Return a `NavLink` (`href`, optional `icon`, `title`, `target`) for the given field name, or `null` for no link. ```java public interface LinkSupplier { NavLink link(String memberName, HttpRequest httpRequest); } ``` The returned `href` and `title` may contain `${state.…}` expressions — they are interpolated in the browser against the live component state, so the link follows the field values as the user edits the form (e.g. `NavLink.to("/orders/${state.orderId}")`). Use it when the destination depends on runtime state or permissions; use `@LinkTo` for the static case. --- ## `Selector<IdType>` Extension point for `@Searchable` fields. Implement this (typically alongside `Listing`) to define what happens when the user clicks a row in the search modal. ```java public interface Selector<IdType> { SelectedItem<IdType> selected(HttpRequest httpRequest); String fieldId(); Selector withFieldId(String name); } ``` `selected()` must return a `SelectedItem` record containing the `id` and a `label`. The framework closes the modal and updates the annotated field with the returned id. `fieldId()` identifies the form field the selector is bound to; `withFieldId(name)` returns a copy of the selector bound to the given field id. Combine with `LookupLabelSupplier` on the same class so the same bean handles both selection and label resolution. --- ## `UploadEnabled` Adds a bulk-import button to a `Listing` toolbar. The uploaded file is sent to `POST /upload` — an endpoint **your application serves** (Mateu ships none: storing files is not a UI concern). It stores the file and answers with its id as the response body; the framework then calls `processUpload()` with that id. ```java public interface UploadEnabled { Object processUpload(String fileId, HttpRequest httpRequest); } ``` Return a `Message` for a synchronous summary, or use `@Action(background = true)` for large file processing. See [Listing — Bulk import](/java-ui-definition/interfaces/listing/#bulk-import--uploadenabled) for full examples. --- ## `Translator` Centralises all user-visible string translation. Mateu calls `translate()` for every label, title, validation message, button text, and alert before sending them to the frontend. ```java public interface Translator { String translate(String text, HttpRequest httpRequest); } ``` The `core` module provides a default implementation backed by Java i18n (`ResourceBundle`). To override it, register a bean in your DI container with higher priority (the mechanism depends on the framework — e.g. `@Primary` in Spring Boot, `@Replaces` in Micronaut, `@Alternative`/`@Priority` in Quarkus/Helidon MP): ```java @Component @Primary public class DatabaseTranslator implements Translator { @Override public String translate(String text, HttpRequest httpRequest) { String locale = httpRequest.getHeaderValue("Accept-Language"); return repo.findTranslation(text, locale).orElse(text); } } ``` See [i18n](/java-user-manual/advanced/i18n/) for the full guide including caching strategies and multi-tenant patterns. --- ## `BeanProvider` Abstraction for dependency lookup. ```java public interface BeanProvider { <T> T getBean(Class<T> clazz); <T> Collection<T> getBeans(Class<T> clazz); } ``` This is more infrastructure-oriented, but still part of the public surface of the DSL. --- ## Mental model Mateu interfaces mostly define extension points in four categories: - fluent UI composition - CRUD integration - dynamic option/label/selection resolution (`LookupOptionsSupplier`, `LookupLabelSupplier`, `Selector`) - dynamic field metadata (`LabelSupplier`, `DescriptionSupplier`, `StyleSupplier`, `RequiredSupplier`, `ReadOnlySupplier`, `DisabledSupplier`, `VisibilitySupplier`, `LinkSupplier`) - dependency and runtime integration --- # Known issues URL: https://mateu.io/reference/known-issues/ > Current limitations of the 3.0 beta that an application can run into, each with its workaround. This page lists the limitations of the current release that you can hit when building or running an app, and what to do about each one. It covers behaviour, not missing features: the full list of what each server and renderer supports is the [feature parity matrix](/reference/parity/). An item leaves this page in the release that fixes it, and the [CHANGELOG](https://github.com/miguelperezcolom/mateu/blob/master/CHANGELOG.md) says so. If you hit something that is not listed here, report it on [GitHub issues](https://github.com/miguelperezcolom/mateu/issues). Security problems go through the private channel in [SECURITY.md](https://github.com/miguelperezcolom/mateu/blob/master/SECURITY.md), never a public issue. ## Deployment ### A servlet context path or a prefix-stripping proxy is not supported The generated index page loads the renderer's assets from `/assets/…` at the **root of the host**. Behind `server.servlet.context-path` or a reverse proxy that strips a path prefix, the page loads but the assets 404, so you get a blank screen. **Workaround:** serve the app at the root of its host, or give the mount the public path you want (`@UI("/admin")`) and route both `/admin/**` and `/assets/**` to the backend. Several Mateu apps behind one host share `/assets/**`, so they must run the same Mateu release. See [Deploy to production](/deploy/production-checklist/). ### Micronaut on JDK 21–23: virtual-thread pinning under load On Java 21+ Micronaut runs the blocking executor that serves Mateu's action endpoints on virtual threads. On JDK 21–23 a virtual thread that blocks inside `synchronized` (verbose logging and some libraries do) pins its carrier thread, and a burst of requests can stall. **Workaround:** run on JDK 24 or later, or set `micronaut.executors.blocking.virtual=false`. See [Micronaut](/java-create-your-project/micronaut/). ### Helidon MP: streamed actions, MCP and YAML mounts see no principal On Helidon MP, Mateu's streamed actions (`LongTask`), the MCP endpoint and YAML mounts run on Helidon's own routing, which does not carry the JAX-RS `SecurityContext`. Without extra wiring they see an anonymous caller, so `@EyesOnly` and YAML `access:` refuse them. **Workaround:** register a `PrincipalResolver` bean that builds the caller from the request. See [Security](/java-user-manual/advanced/security/). ### Micronaut and Quarkus are stricter than the JSON-body rule Mateu's endpoints accept a body declared `application/json` or any `application/*+json` (everything else answers 415). Two frameworks narrow that further before Mateu sees the request: Micronaut's sync, SSE and YAML-mount endpoints accept only `application/json` (a `application/vnd.x+json` body answers 415 there, while `/mateu/mcp` and every other adapter take it), and Quarkus REST refuses `application/json ;charset=UTF-8` with a space before the `;`. **Workaround:** send exactly `Content-Type: application/json` (with or without `; charset=…`) — what every Mateu renderer, native app and the sidecar send. ### Proxies must not buffer server-sent events Long-running actions stream their progress over server-sent events. A proxy that buffers the response (nginx does by default) delivers it all at the end, or times out. **Workaround:** disable buffering for the action endpoint (`proxy_buffering off;` in nginx) and raise its read timeout above your longest task. ### Permissions in static bundles and in Play are cosmetic `access:`, `eyesOnly`, `readOnlyUnless` and `disabledUnless` are enforced by the server on every request. A static bundle has no server, and the visual editor's Play mode shows the page unrestricted, so there they decide nothing. **Workaround:** never rely on a static bundle to hide data: the API behind it must enforce access itself. See [Permissions in YAML](/define/yaml/permissions/). ## Renderers ### Redwood: light theme only The Redwood renderer has no dark mode. It ignores `@App(themeToggle = true)`, a stored dark choice and the operating system's `prefers-color-scheme`. **Workaround:** use the Vaadin renderer if your users need a dark theme. ### Redwood: federation does not know static remotes or remote custom elements On Redwood, a federated menu (`RemoteMenu`) works against a remote that is a running Mateu backend. A remote that is a **static bundle**, and a remote screen that uses its own **custom web components**, are not loaded. **Workaround:** serve the remote from a backend, or use the Vaadin renderer for that shell. See [Using external Mateu UIs](/java-user-manual/build/using-external-mateu-uis/). ### A remote screen's own scripts need CORS from the remote When a shell embeds a screen from another Mateu backend, Mateu's CORS settings (`mateu.cors.allowed-origins`) cover only its own endpoints (`…/mateu/**`). A script an `Element` of the remote screen imports (`import: /x.js`) is a plain static file of the remote. **Workaround:** open that path to the shell's origin on the remote (on Spring, a `CorsRegistry` mapping). See [Using external Mateu UIs](/java-user-manual/build/using-external-mateu-uis/). ### Multi-value fields do not read `optionsSource` A single-select field takes its options from a REST source (`@RestOptions`, `optionsSource`). A multi-value field (`multiSelect`, `listBox`, multi-select `combobox`) does not: it reads static options or a remote `search-<field>` action. **Workaround:** give the field an options supplier or a `@Lookup` search on your server, which can call the external endpoint itself. ### React Native: saved views and column choices last one session On React Native, saved listing views and the column chooser's show/hide choices are kept in memory and reset when the app restarts; columns cannot be reordered there. The web renderers and IntelliJ persist them. **Workaround:** none yet. Server-side defaults (the listing's declared columns and filters) are what a user sees after a restart. ### Touch and desktop adaptations Some interactions have no direct equivalent on a device and are adapted rather than reproduced: React Native has no hover (popovers and tooltips open on press / long-press), no row dragging (a "Move to…" picker), no hardware keyboard shortcuts (app quick-launch codes only), and shows `Workflow`, `FormEditor` and `Bpmn` read only. IntelliJ shows `Workflow` and `FormEditor` read only, uses a file picker for photo capture and searches only the loaded options of a searchable picker. **Workaround:** edit workflows and forms on the web. The full list is in the [renderer coverage tables](/reference/parity/#renderers). ## .NET and Python servers The .NET and Python servers emit the same wire as Java for the features they support. These Java features are **not ported yet**; an app that needs them must be written in Java for now: - the editable-view orchestrators — `EditableView`, `AutoEditableView`, `MasterDetailView` (a read view with an Edit button that flips to an editor and back). **Workaround:** a CRUD with `editInDrawer`, or a view whose action returns the editor; - class-level `@AutoSave` (the archetypes that auto-save, such as `CollectionDetail`, do work); - `@ViewToolbarButton` — a CRUD record's view page has the fixed Back / Add another / Edit toolbar; - `type: AppShell` YAML definitions — author the shell in code (`AppShell` + `AppSupplier`); - the static-bundle exporter (`mateu-bundle:bundle` is a Java build plugin); - `Dialog` placement and `draggable`/`resizable`; - `@MainFilter`, `@HiddenIn*` and `@Section(sticky, columns, style)`; - Python only: a class-level `read_only_unless` — put it on each field. Listing filters (ranges, multi-select) are applied in memory in both ports; override `find` to push them to your database. The complete list is [What is still Java-only](/reference/parity/#what-is-still-java-only). ### .NET 8 leaves Microsoft support on 2026-11-10 The .NET packages target `net8.0` and `net10.0`. Microsoft ends support for .NET 8 on 10 November 2026; Mateu keeps the `net8.0` target for the 3.0 line, but security updates of the runtime itself stop then. **Workaround:** move the app to .NET 10 (LTS). ## Tooling - **Spring Boot 3 is not supported.** The Spring adapters are built and tested against Spring Boot 4 only. Upgrade to Boot 4 (see [Prerequisites](/java-create-your-project/prerequisites/)). - **The IntelliJ plugin supports IDE builds 2025.2 and 2025.3** (`252`–`253.*`). Newer IDE lines are enabled once the plugin verifier passes on them. - **The Figma pipeline and the visual editor are previews**: they are not covered by the stability promise (see [Stability & versioning](/reference/stability-and-versioning/)). --- # Language Rosetta URL: https://mateu.io/reference/language-rosetta/ > The same Mateu declaration in Java, C# and Python — side by side. Every Mateu server emits the **same wire model**, so the concepts are identical across languages — only the declaration syntax changes. This page maps the idioms; the concept documentation (UX patterns, execution model, wire contract) applies to all three. ## Declaring views and apps | Concept | Java | C# (.NET) | Python | |---|---|---|---| | Routed view | `@UI("/route")` | `[UI("route")]` | `@ui("route")` | | Title | `@Title("...")` | `[Title("...")]` | `@title("...")` | | App shell | `@UI` class with `@Menu` fields | `[App("...")]` class with `[MenuItem]` methods | `@app("...")` class with `@menu_item` methods | | App home page | app class implements `HomeRouteSupplier` | app class implements `IHomeRouteSupplier` | app class subclasses `HomeRouteSupplier` (`home_route()`) | | CRUD | `extends AutoCrud<T>` + `store()` | `class X : Crud<T>` + `Fetch(...)` | `class X(Crud[Thing])` + `fetch(...)` | | Wizard | `extends Wizard` + step fields | `Wizard` + `[Step]` | `Wizard` + `Step()` | ## Fields | Concept | Java | C# | Python | |---|---|---|---| | Required | `@NotNull` / `@NotEmpty` | `[Required]` | `Annotated[str, Required()]` | | Label | `@Label("...")` | `[Label("...")]` | `Annotated[str, Label("...")]` | | Section | `@Section("...")` | `[Section("...")]` | `Annotated[str, Section("...")]` | | Explicit stereotype | `@Stereotype(...)` | `[Stereotype("...")]` | `Annotated[str, Stereotype("...")]` | | Multiline | `@Multiline` | `[Multiline]` | `Annotated[str, Multiline()]` | | Password | stereotype `password` | `[Password]` | `Annotated[str, Password()]` | | Money | `@Stereotype(money)` | `[Money]` | `Annotated[str, Money()]` | | Plain text (read-only) | `@PlainText` | `[PlainText]` | `Annotated[str, PlainText()]` | | Radio group | `@UseRadioButtons` | `[UseRadioButtons]` | `Annotated[MyEnum, UseRadioButtons()]` | | Nav link | `@LinkTo("/x/${state.id}")` / `LinkSupplier` | `[LinkTo("...")]` / `ILinkSupplier` | `Annotated[str, LinkTo("...")]` / `link(member_name)` | | Signature capture | `@Signature` | `[Signature]` | `Annotated[str, Signature()]` | | Photo capture | `@PhotoCapture` | `[PhotoCapture]` | `Annotated[str, PhotoCapture()]` | | Tree select | `@TreeSelect(leavesOnly=…)` | `[TreeSelect(leavesOnly: …)]` | `Annotated[str, TreeSelect(leaves_only=…)]` | | Numeric range filter (crud listing) | `@RangeFilter` | `[RangeFilter]` | `Annotated[float, RangeFilter()]` | | Static options | class implements `OptionsSupplier` | class implements `IOptionsSupplier` | the view's `options(field_name)` method | ## Actions & page features | Concept | Java | C# | Python | |---|---|---|---| | Button | `@Button` method | `[Button]` method | `@button()` method | | Toast message | return `Message` | return `Message` | return `Message` | | KPI | `@KPI` field | `[Kpi("Open tickets")]` method | `@kpi("Open tickets")` method | | FAB | `@Fab(icon=…)` method | `[Fab("icon")]` method | `@fab("icon")` method | | Keyboard shortcut | `@Action(shortcut="ctrl+s")` | `[Shortcut("ctrl+s")]` | `@shortcut("ctrl+s")` | | Compact mode | `@Compact` | `[Compact]` | `@compact` | | Adaptive layout | (default heuristics) | `[AutoLayout]` | `@auto_layout` | | Banner | `@Banner(theme=…)` method | `[Banner(BannerTheme.Info, "…")]` method | `@banner(BannerTheme.INFO, "…")` method | | Header badge | `@BadgeInHeader` field | `[HeaderBadge("success")]` | `Annotated[..., HeaderBadge(color="success")]` | | App context selector | `@AppContext` field | `[AppContext]` member | `@app_context` method | | Emit event | `UICommand.dispatchEvent` / `@Emits(name=…)` | `[Emits("order-created")]` | `@emits("order-created")` | | Subscribe to event | `@SubscribeTo(event=…, action=…)` | `[SubscribeTo("event", "action")]` | `@subscribe_to("event", "action")` | | Unsaved-changes guard | `@ConfirmOnNavigationIfDirty` | `[ConfirmOnNavigationIfDirty]` | `@confirm_on_navigation_if_dirty` | | i18n | `Translator` | `ITranslator` | `Translator` | Exact signatures can drift — the per-language manuals ([C#](/csharp-user-manual/), [Python](/python-user-manual/)) and each backend's golden tests (`backend/dotnet/test`, `backend/python/tests`) are the source of truth. ## What stays identical - The **wire**: `POST /{baseUrl}/mateu/v3/sync/{route}` → `UIIncrement` JSON. - The **renderers**: web (Vaadin, Redwood) and native (the IntelliJ plugin, React Native) render any server without client changes. - The **concepts**: everything under [UX Patterns](/ux-patterns/) and the execution model. For what each server supports today, see the [feature parity matrix](/reference/parity/). --- # Migrating from alpha URL: https://mateu.io/reference/migrating-from-alpha/ > Every rename, removal and default change between the 3.0 alphas and the beta, with the one-line fix for each. The 3.0 alphas changed the API in place while it was being shaped. This page collects **every change that can break an app written against an earlier alpha** — renames, removals, and defaults that now behave differently — so you can upgrade in one pass. From the beta on, changes follow the [stability policy](/reference/stability-and-versioning/) instead: deprecated for one minor first, never removed silently. Work through the sections that apply; the compiler finds most of them for you (the Java renames and removals are compile errors), the [default changes](#defaults-that-changed) are the ones to read. ## Maven artifacts Every published artifact now carries the `mateu-` prefix (the group stays `io.mateu`). The old coordinates still resolve — each one is published as a **relocation pom** pointing at the new id, so an old build keeps working and Maven prints a warning naming the replacement — but they are deprecated: update your poms (or import `io.mateu:mateu-bom` and drop the versions altogether). | Before (`io.mateu:…`) | Now (`io.mateu:…`) | |---|---| | `uidl` | `mateu-uidl` | | `dtos` | `mateu-dtos` | | `core` | `mateu-core` | | `mvc-core` | `mateu-mvc` | | `webflux-core` | `mateu-webflux` | | `micronaut-core` | `mateu-micronaut` | | `quarkus-core` | `mateu-quarkus` | | `helidon-mp-core` | `mateu-helidon-mp` | | `vaadin-lit` | `mateu-vaadin` | | `redwood` | `mateu-redwood` | | `annotation-processor-indexer` | `mateu-annotation-processor-indexer` | | `annotation-processor-core` | `mateu-annotation-processor-core` | | `annotation-processor-mvc` | `mateu-annotation-processor-mvc` | | `annotation-processor-webflux` | `mateu-annotation-processor-webflux` | | `annotation-processor-micronaut` | `mateu-annotation-processor-micronaut` | | `annotation-processor-quarkus` | `mateu-annotation-processor-quarkus` | | `annotation-processor-helidon-mp` | `mateu-annotation-processor-helidon-mp` | | `mateu-bom`, `mateu-bundle-maven-plugin` | unchanged | An old id in `<annotationProcessorPaths>` is followed too, but **silently** (Maven only warns for dependencies) — so search your poms for the old processor ids rather than waiting for a warning. The renderer switch of the demos follows suit: `-Dmateu.renderer=mateu-vaadin|mateu-redwood`. The parent poms (`backend`, `shared`, `mvc`, `webflux`… → `mateu-parent`, `mateu-shared-parent`, `mateu-mvc-parent`…) were renamed too; nothing outside Mateu should reference them, so they have no relocation. ## Renames | Before | Now | What to do | |---|---|---| | `CrudRepository<T>` / `CompositionCrudRepository<T>` | `CrudStore<T>` / `CompositionCrudStore<T>` | Rename the type. Same methods. | | `AutoCrud.repository()` | `AutoCrud.store()` | Rename the override. | | `ListingBackend<Row>` | `Listing<Row>` | Rename. `search(SearchRequest, HttpRequest)` is the single entry point; read typed filters with `Filterable.filters(request)`. | | `ReactiveListingBackend<Row>` | `ReactiveListing<Row>` | Rename. | | `io.mateu.core.infra.declarative.Listing` (base class) | `io.mateu.uidl.interfaces.Listing` (interface) | Implement the interface; `@Toolbar` actions, selectors and row-method invocation moved into it. | | `Searchable` (entity interface: "search me by this text") | `SearchableText` | Rename on your entities. The name `Searchable` now means the **listing capability** (show a search box) — see below. | | `Crud.saveNew(...)` | `Crud.create(...)` | Rename; `save(...)` now returns the id. | ## Removed | Removed | Replacement | |---|---| | `@Route`, `@Routes`, `@HomeRoute` | `@UI` is the only routing annotation and declares a **mount**. Screens inside a mount are declared in [`routes.yaml`](/concepts/routes-and-mounts/) or supplied in code by a `RouteEntrySupplier` bean. The home route is the app's first menu item, or what `HomeRouteSupplier` returns. See [Route annotations](/java-ui-definition/annotations/route/) for the step-by-step. | | The `Deleteable` view-class marker | Custom `Crud`s show **Delete** by default; subtract it with `@NotDeletable`. | | The `AutoCrud.store()` fallback | `store()` is **abstract**: every `AutoCrud` / `FilteredAutoCrud` subclass must override it. | | The `route-registrations` index file | Nothing to do — the annotation processors write `ui-registrations` only. Rebuild modules compiled by an old processor. | | `@Tabs` (class) | Nothing — consecutive fields sharing a `@Tab` name already form one tab strip. Delete the annotation. | | `@Accordion`, `@AccordionPanel` | `@FoldedLayout` on the class: each `@Section` becomes a collapsible panel. (`@Accordion` never had runtime retention.) | | `@HorizontalLayout`, `@VerticalLayout`, `@SplitLayout`, `@Scroller` (annotations) | `@Zones`/`@Zone` for side-by-side sections, `@MasterDetail`, or the fluent `HorizontalLayout`/`VerticalLayout`/`SplitLayout`/`Scroller` records (unchanged) in a `ComponentTreeSupplier`. | | `@H1` … `@H5` | `@Text(container = TextContainer.h1)` … `h6`. | | `@Option` (on enum constants) | `@Label` on the constant — or nothing: an unlabelled constant is humanized (`OUT_OF_STOCK` → "Out of stock"). | | `@State` | Nothing — every field already travels in the component state; rules read it as `state.<field>`. | | `@RowAction` | A `ColumnActionGroup` field on the row (`new ColumnAction("approve", "Approve")`) runs the listing method `approve(Row row)`. | | `@BaseRoute` | `basePath:` in the route file (`type: Routes`). | | `io.mateu.uidl.fluent.ActionType` (an empty enum) | Nothing — it had no constants and nothing used it. | | The `mateu-export-excel` and `mateu-export-pdf` modules (and their old ids `export-excel` / `export-pdf`) | Mateu ships UI only: the Export buttons, columns, rows and the download stay, but the **file engine** is yours. Implement `io.mateu.uidl.interfaces.ListingExporter` (one bean per format, with Apache POI, PDFBox, OpenPDF… as your own dependency) — two implementations to copy are in [Export engines](/java-ui-definition/interfaces/listing/#export-engines). Without one, the Excel / PDF buttons are simply not shown. CSV still works out of the box. | | `ExcelExporter`, `PdfExporter`, `CsvExporter` (`io.mateu.uidl.interfaces`) | `ListingExporter`: `ExportFormat format()` + `ExportedFile export(ListingExport, HttpRequest)` — it receives the format, title, columns, ALL filtered rows and the search, and returns the bytes plus an optional media type and filename. | | .NET `IExcelExporter` / `IPdfExporter` / `ICsvExporter` and the built-in Excel / PDF writers | `IListingExporter` (`Format` + `Export(ListingExport)` → `ExportedFile`), registered as a service; see the [C# manual](/csharp-user-manual/#listing-exports). CSV stays built in. | | Python `mateu-ui[export]` extra (openpyxl / reportlab) and the built-in Excel / PDF writers | a `ListingExporter` subclass of yours in a module you register (`add_mateu(app, my_module)`), discovered like the other suppliers; see the [Python manual](/python-user-manual/#exports). CSV stays built in. | | The `mateu-agent-cli` / `agent-cli-companion` modules (never published; the CLI bridge for the AI chat) and the chat's probe of a local companion on `127.0.0.1:8776` | Point `@AI(sse = …)` at your own agent endpoint — the chat panel and its SSE contract are unchanged ([AI assistant](/ai/)). | | Renderers: SAP UI5, Oracle JET (`redwood-oj`), PatternFly (`redhat`), Salesforce Lightning (`slds`); the JavaFX and Compose native renderers | Web: `mateu-vaadin` or `mateu-redwood` (Oracle Visual Builder). Native: React Native and the IntelliJ plugin. Your UI code does not change — swap the renderer dependency. | All the annotations in the rows above had **no effect** in any alpha — nothing read them — so removing one changes no screen; it only makes the compiler point at it. ## Deprecated in 3.0-alpha.410 (still working) The pre-beta API freeze review deprecated these instead of removing them: they keep compiling and working, the compiler warns, and they will be removed after the deprecation period. Each Javadoc names its replacement. | Deprecated | Use instead | |---|---| | `AppVariant.HAMBURGUER_MENU` (misspelled; also in YAML `variant:`) | `AppVariant.HAMBURGER_MENU` — renders the same. .NET: `AppVariant.HamburgerMenu`; Python: `AppVariant.HAMBURGER_MENU` (the old string warns). Since 3.0-alpha.412 it is also the wire value — see [Wire and renderers](#wire-and-renderers) | | `@GenericClass` | nothing — it was never read; declare the field with its type argument (`List<MyDto>`) | | `io.mateu.uidl.annotations.ActionType` | `@Toolbar` / `@Button` / `@Hidden` on the method | | `ActionPosition`, `ActionStereotype`, `ActionThemeVariant` (empty enums in `io.mateu.uidl.fluent`) | nothing — they had no constants; style buttons with `ButtonStyle` / `ButtonColor` / `ButtonVariant` | | `Binding`, `BindingSource` | nothing — components bind by convention (`FormField` id ↔ property, `Button` actionId ↔ method); expressions read `state.*` / `appState.*` | | `ClientSideEvent` | `UICommand.dispatchEvent(name, payload)` + `@SubscribeTo` | | `Destination` | `UICommand.navigateTo(route)`, or return a `URI` from the action | | `ListAdapter<Filters, Row>` | `Listing<Row>` (`search(SearchRequest, HttpRequest)`) | | `io.mateu.uidl.layout.ColumnLayoutSelector` | declare `gridLayout()` — `GridLayout.auto` is a table | | 28 unreachable wire DTOs in `io.mateu.dtos` (`JourneyDto`, `ViewDto`, `BadgeColorDto`, `SortCriteriaDto`, …) | nothing — no live DTO references them; the wire is unchanged | | .NET `DashboardLayout` / `ContentLayout` (now `[Obsolete]`, like Java's `@Deprecated`); Python ones warn | `ResponsiveGrid` | ## Deprecated in 3.0-alpha.412 (still working) The owner's pre-beta API decisions. Every item is an addition plus a deprecation: the old name keeps compiling and working (Java `@Deprecated(forRemoval = true)`, .NET `[Obsolete]`, Python `DeprecationWarning`) until it is removed after the deprecation period. | Deprecated | Use instead | |---|---| | `BadgeSupplier` (`List<Badge> badges()`) | `HeaderBadgesSupplier` (`List<Badge> headerBadges()`) — named after `@BadgeInHeader`. Both are read; the new one wins if a page implements both | | `Button.getActionId()` | `Button.resolvedActionId()` — same value: the declared id, else derived from the label. `actionId()` is the declared id only. Nothing changes on the wire | | `@KeycloakSecured` | your framework's authentication (an OIDC login / resource server for Keycloak) — Mateu reads the principal it authenticates, or a `PrincipalResolver` bean. See [Security](/java-user-manual/advanced/security/) | | `AppVariantDto.HAMBURGUER_MENU` (wire DTO) | `AppVariantDto.HAMBURGER_MENU` | | The settings `mateu.layout.inference` and `mateu.page.inference.disabled` (they warn once) | `mateu.layout.inference.enabled` and `mateu.page.inference.enabled` — mind the polarity: `disabled=true` is `enabled=false`. .NET: the AppContext switches `Mateu.LayoutInference` / `Mateu.PageInference.Disabled` → `Mateu.LayoutInference.Enabled` / `Mateu.PageInference.Enabled`. See [Global switches](/ux-patterns/layout-inference/#global-switches) | | Python `Size(min=, max=)` (the length constraint) | `Length(min=, max=)` — same fields; in Java and .NET `Size` is a component's sizing intent | | .NET `[Secured("x")]`, Python `@secured("x")` | `[EyesOnly(Permissions = new[] { "x" })]` / `@eyes_only(permissions=["x"])` on the class. **`[Secured]`/`@secured` are now enforced (they were silently ignored before)**: exactly like `EyesOnly(permissions = "x")`, the view and its actions are refused (403) to a caller without the permission or with no principal, and the menu entries leading to it are hidden. A view that carried it was open to everyone until 3.0-alpha.412 — check that the callers who need it hold the permission (and that your framework's security is configured, or nobody does) | **Moved, nothing to change**: the .NET code-authoring types (`IRouteEntrySupplier`, `IAppSupplier`, `IMenuSupplier`, `AppShell`, `RouteEntry`) now live in the `Mateu.Uidl` package with the same full names (`Mateu.Core.*`); `Mateu.Core` forwards them, so existing code and binaries keep working, and a UI-only module no longer needs `Mateu.Core` to use them. **.NET engine now internal (3.0-alpha.429)**: `SyncHandler`, `MateuRegistry`, `ReflectionMapper` and the rest of the `Mateu.Core` engine are `internal`. An app built on `AddMateu` / `MapMateu` changes nothing; code that constructed the engine itself must go through `Mateu.AspNetCore`, and a `MateuRegistry.RegisterAdapter(adapter)` call becomes an `IComponentAdapter` service registration. ## Deprecated in 3.0-beta (still working) | Deprecated | Use instead | |---|---| | The Python top-level packages `mateu_uidl`, `mateu_dtos`, `mateu_core`, `mateu_fastapi` | `mateu_ui.uidl`, `mateu_ui.dtos`, `mateu_ui.core`, `mateu_ui.fastapi` — the `mateu-ui` wheel now installs one top-level package, `mateu_ui`. The old names import the SAME modules (submodules too: `from mateu_core.mapper import ReflectionMapper` still works) and each emits one `DeprecationWarning` naming the new path; type checkers only see the new paths. They are kept for the whole 3.x line. Migrating is a prefix replace | ## Defaults that changed These compile unchanged and **behave differently**. Check each against your screens. | Area | Before | Now | To get the old behaviour | |---|---|---|---| | Enum labels | the raw constant (`OUT_OF_STOCK`) | the name humanized ("Out of stock") | label each constant explicitly (`@Label`) | | Rich text (`@Stereotype(richText)`) | the value was Quill Delta JSON | the value is **HTML** | values stored by the old editor still open and are saved as HTML on the next edit — migrate stored data if other systems read it | | `GridLayout.auto` | chose table / list / cards / master-detail from the available width | always a **table** | declare `gridLayout()` explicitly (`cards`, `list`, `masterDetail`) | | Clicking a listing row (a navigable listing: a view per row, or `rowRoute`) | only the id link opened the record | a click **anywhere on the row** opens it (and Enter on a focused row); the selection checkbox, inline editors and display columns — buttons, links, menus, action groups, components, columns with their own action — keep their own behaviour | — (put a per-row action in a column with its own `actionId` if a click there must not open the record) | | Listing search box | always shown | shown only if the listing implements `Searchable` | add `Searchable` to the listing (`AutoCrud` and `Crud` already have it) | | Listings without interaction capabilities | opened empty | **search on opening** (`Listing.searchesOnOpening()` defaults to `true`) | override `searchesOnOpening()` to return `false` | | `@Section(columns = …)` | default `1`, and an explicit `1` was ignored | default `0` = inherit from `@FormLayout`; an explicit `columns = 1` is honoured | remove an explicit `columns = 1` you did not mean | | CORS | the generated controllers carried `@CrossOrigin` (any origin; Micronaut also with credentials) | **off**: same-origin only | set `mateu.cors.allowed-origins` (comma-separated; optionally `mateu.cors.allow-credentials=true`, never with `*`) — Python: `add_mateu(app, cors_origins=[...])` | | Roles for `@EyesOnly` / `@ReadOnlyUnless` / `@DisabledUnless` / YAML `access:` | read from the Bearer token's payload **without verifying it** — anyone could forge them | **Mateu does not authenticate**: roles come only from the principal your framework authenticated (Spring Security, Quarkus/Micronaut/Helidon security, ASP.NET Core authentication, Python's `request.state.mateu_identity` / `AuthenticationMiddleware`) or a `PrincipalResolver` bean. A token on its own grants nothing; with no security configured, restricted UI is hidden for everyone and a WARN at startup says so | configure your framework's security (see [Security](/java-user-manual/advanced/security/#how-authorization-works)) — there is no opt-out. Python: `jwt_identity_provider` and the `jwt` extra are gone; verify the token in your app and set `request.state.mateu_identity = identity_from_claims(claims)` | | .NET `[Secured("x")]` / Python `@secured("x")` on a view | silently ignored: the view was open to everyone | **enforced** like `EyesOnly(permissions = "x")`: 403 for the view and its actions without the permission (or with no principal), menu entries to it hidden | — (it was always meant to restrict; grant the permission to the callers who need the view) | | `@EyesOnly` fields in the state | hidden in the form but their value travelled in the component state | left out of the state for callers who may not see them | — | | Spring component scan | the generated `…Config` scanned **all of `io.mateu`**, sweeping in the beans of any library under `io.mateu.*`; the docs asked for `scanBasePackages = "io.mateu"` | Mateu's beans come from its adapter's auto-configuration (`io.mateu.MateuAutoConfiguration`), which scans only Mateu's own packages | drop `"io.mateu"` from `scanBasePackages`; if your OWN code lives under `io.mateu.*` (outside the main class's package), name that package there; a third-party UI module you used to get for free (e.g. EventConductor's console) is mounted with `mateu.ui.modules=<its package>` — see [Using external Mateu UIs](/java-user-manual/build/using-external-mateu-uis/) | | Which methods an `actionId` can run (Java) | every public method of a view model | **strict action mode**: a method marked as an action (`@Action`, `@Button`, `@Toolbar`…) or one whose id the view advertises (a fluent button, a trigger, `@OnRowSelected`, a menu rule…); an unadvertised public method answers 403 — as the .NET and Python backends always did | mark the handler `@Action` (undo targets, row actions, methods only a test or another backend dispatches); or `mateu.actions.strict=false` while you migrate | | CRUD save of read-only / hidden fields | the posted state wrote every field, an edit could even change the id (a new row next to the edited one) | an edit keeps the loaded record's id and its read-only / hidden-in-editor values; a create takes read-only / hidden-in-create fields from a fresh creation form | a value a `buildCreationForm` override pre-fills into a read-only field: set it in `create()` (or the store) instead | | MCP endpoint (`POST /mateu/mcp`) | on | **off** | `mateu.mcp.enabled=true` | | Request bodies of Mateu's endpoints (3.0-beta.6) | a `POST` to `<baseUrl>/mateu/v3/**` or `/mateu/mcp` with `text/plain`, a form encoding or no `Content-Type` ran (on Micronaut, Quarkus, Helidon MP, .NET, Python, and the MCP endpoint everywhere) | **415** unless the body is declared `application/json` / `application/*+json` — the requests a cross-site page can forge without a preflight are refused on every adapter | — (send `Content-Type: application/json`; the renderers, native apps and the sidecar already do; `…/mateu/v3/client-log` and `/mateu/dev/**` are exempt) | | `__validate__` on the sync endpoint (3.0-beta.6) | answered anyone | **403** unless it is an MCP tool call or the app runs with `mateu.mcp.enabled=true` or in dev mode | enable one of those where the sidecar's authoring tools are used | | `update-row` (inline editing) (3.0-beta.6) | advertised and accepted by every crud, writing any posted field | offered only by a crud with `@InlineEditing` (and `canEdit()`); read-only fields keep the stored value; an unknown id is refused, not inserted | annotate the crud `@InlineEditing` | | `${secret.X}` in proxied REST sources | fell back to ANY environment variable named `X` | a `SecretsProvider` bean first, then only the env var `MATEU_SECRET_X` | rename the variable to `MATEU_SECRET_X` | | Unexpected exceptions in actions | the exception class and message in the toast | "Something went wrong — An unexpected error occurred. Reference: …", the details in the server log under that reference | throw `io.mateu.uidl.UserFacingException(title, message)` for messages meant for the user; `MATEU_ERRORS_DETAILED=true` restores the raw text in development | | Client-side JavaScript (`RunJS` rules, RunJS menu leaves, an action's `js`) | always on | **off** — expressions (`${…}`, rules, `@Hidden(…)`) run in Mateu's own evaluator and need no `'unsafe-eval'` | `<meta name="mateu-allow-run-js" content="true">` (or `configureRunJs(true)`), and `'unsafe-eval'` in that page's CSP | | Quarkus | `quarkus-spring-di` came with the adapter | not brought in | declare `quarkus-rest-jackson` (and `quarkus-spring-di` only if your own beans need it) | | Spring `ObjectMapper` bean | Mateu registered one named `objectMapper` | named `mateuObjectMapper`, not injected into your beans | declare your own `ObjectMapper` bean if you relied on Mateu's | ## Wire and renderers - Every response now carries `wireVersion` (`3.0`). The first-party renderers check it and show a clear message when the server speaks another wire major; a custom renderer should do the same and ignore unknown fields and component types — see the [wire specification](/reference/wire-specification/). - **Servers now send `HAMBURGER_MENU`** (3.0-alpha.412) where they used to send the misspelled `HAMBURGUER_MENU` — Java, .NET and Python alike, whichever spelling you declared. Every first-party renderer accepts both spellings (web and Redwood since 3.0-alpha.387; React Native and IntelliJ treat every menu variant the same), so this only matters with a **renderer that predates the change or a custom one**: an old renderer plus a new server is a mismatch — upgrade the renderer together with the server (they ship together), and make a custom renderer accept both. - The **Java wire DTOs** (`mateu-dtos`) are outside the Java binary-compatibility promise: the contract is the JSON. A new optional wire field replaces a DTO record's canonical constructor, so build DTOs through their builders. See [Stability & versioning](/reference/stability-and-versioning/#the-wire-dtos-json-not-java-binaries). - The Redwood renderer serves Mateu routes **by path** (`/products`), not by hash (`#/products`). Bookmarks with a hash keep working in the statically served VB app only. ## A quick upgrade checklist 1. Rename the Mateu artifacts in your poms (`mvc-core` → `mateu-mvc`…, table above), bump `mateu.version` to the latest release and rebuild — fix the compile errors with the tables above (most are a rename). 2. Move any `@Route`-annotated inner screen into `routes.yaml` (or a `RouteEntrySupplier`). 3. Click through each listing: search box present where you want it, layout as expected, Delete where it should be. 4. Check forms with enums (labels) and rich text (stored format). 5. Read the beta release notes for the security defaults (CORS, MCP) — and if any screen uses `@EyesOnly` / `@ReadOnlyUnless` / `@DisabledUnless` / `access:`, configure your framework's security (Mateu reads the principal it authenticates), or that UI is hidden for everyone. ## Related - [Stability & versioning](/reference/stability-and-versioning/) — what is public API from the beta on. - [CHANGELOG](https://github.com/miguelperezcolom/mateu/blob/master/CHANGELOG.md) --- # Feature parity matrix URL: https://mateu.io/reference/parity/ > What each server (Java, .NET, Python) and each renderer supports today. Mateu's contract is the wire: any server can serve any renderer. Coverage differs by implementation — this page is the honest snapshot, and the single place to update when something is ported. ✅ full · 🟡 partial (see note) · — not yet. ## Servers The Java server is the reference implementation; the .NET and Python servers emit the same wire for the surface below (verified by golden-JSON tests in `backend/dotnet/test` and `backend/python/tests`, and by the shared [conformance corpus](#the-conformance-gate)). A 🟡 row names what the ports lack; the gaps that are not features of their own — wire component types, envelope members, authoring annotations — are listed after the table, in [What is still Java-only](#what-is-still-java-only). When something is ported, flip its row here in the same change. | Feature | Java | .NET | Python | |---|---|---|---| | Forms, sections, field types, validation. Field help (`[Help]` / `Help()` → `description`), `[SliderMin]`/`[SliderMax]` (`SliderMin()`/`SliderMax()`) and the fluent `FormField`'s `placeholder`/`autofocus`/`step` are in both ports (conformance cases `field-help`, `field-hints`). Ports: no `@Section(sticky, columns, style)`, `@MainFilter`, `@HiddenIn*` | ✅ | 🟡 | 🟡 | | CRUD (list / detail / edit / new / save / delete) | ✅ | ✅ | ✅ | | App shell + menus + navigation. Ports: no `@App(layout, backLink, ask…)`, and 25 of the 62 `AppDto` members are never emitted (see [envelope members](#envelope-members)) | ✅ | 🟡 | 🟡 | | App shell + menus authored IN CODE (Java `AppSupplier`/`MenuSupplier` returning a fluent `AppShell`; .NET `IAppSupplier`/`IMenuSupplier` + `AppShell`; Python `AppSupplier`/`MenuSupplier` + `AppShell`) — the whole shell (or just the menu) computed at request time, overriding the static `@App`/`@Menu` declarations | ✅ | ✅ | ✅ | | [App shell as data](/define/yaml/app-shell/) (`type: AppShell` definition bound to a mount route) with its FLOWS — `actions:` with `steps:` that a menu `RuleLink` (`RunAction` rule) runs client-side, no round-trip — plus `widgets:` and the header switches `themeToggle`/`commandCenter`/`chromeless`/`accessKeys`. Code-built shells carry the same (`AppShell.builder().action(...)`). The ports have no `type: AppShell` definitions: N/A there | ✅ | N/A | N/A | | Wizards (incl. branching, cross-step state, `@WizardProgress` BAR/STEPS/RAIL) | ✅ | ✅ | ✅ | | CRUD create/edit in a drawer (`editInDrawer` — save closes + refreshes the listing in place) | ✅ | ✅ | ✅ | | Collection-detail / general-overview archetypes (`CollectionDetail<Row>`, `GeneralOverview<Row>`) + fluent `FormField` | ✅ | ✅ | ✅ | | Guided import wizard (`ImportWizard<Row>`: CSV upload/paste, auto-mapping grid, validation report, typed import) | ✅ | ✅ | ✅ | | Page decorations (subtitle, banners, badges, KPIs, FABs) | ✅ | ✅ | ✅ | | Action-returned banners with an explicit mode (`PageBanners.replace`/`append`; .NET `PageBanners.Replace(...)`/`.Append(...)`, Python `PageBanners.replace(...)`/`.append(...)`; a bare `PageBanner`/list replaces everywhere) | ✅ | ✅ | ✅ | | Fluent `Card` with component slots (title, subtitle, media, header…, content, footer) | ✅ | ✅ | ✅ | | An app with no declared home lands on its first menu item; an app under a sub-path accepts mount-absolute routes; the chrome language follows `Accept-Language`; an error toast stays until dismissed; a `List<Enum>` with no stereotype is a multi-select | ✅ | ✅ | ✅ | | Header overline + title placeholder (`@Overline`/`@TitlePlaceholder`; Java also has `OverlineSupplier`/`TitlePlaceholderSupplier`, the ports carry only the declarative form — same as `@Subtitle`) | ✅ | ✅ | ✅ | | Tabs, stereotypes, shortcuts, compact, dirty guard | ✅ | ✅ | ✅ | | Redwood pattern gaps (2026-10-10): display records (`Toggle` + `WizardDisplay`/`CrudDisplay`/`GeneralOverviewDisplay`), wizard drafts/skip/early completion/`beforeStepNavigate` (ports: steps by number), edit-drawer save-and-next + error banner, `GeneralOverview` info slot, foldout `summary`, `DataManagement` docked panels, header `RecordSwitcherSupplier`, `@Section` edit/add/view-more, hero tone, `Announce` command, smart-search pre-search content — see [Page templates](/ux-patterns/page-templates/#display-options-one-tri-state-grammar) | ✅ | ✅ | ✅ | | Adaptive layout inference (radios, folding, tabs) | ✅ | ✅ | ✅ | | Nav links (`@LinkTo` / link supplier) | ✅ | ✅ | ✅ | | [Route registry](/concepts/routes-and-mounts/) (`specs/ui/routes.yaml`: definition + view model + fixed/default params per route, merged over the derived table). Both ports mirror the model, the matching, the precedence and the definition lookup; neither has a static-bundle exporter, so nothing ships the table to a browser there | ✅ | ✅ | ✅ | | Route registry authored IN CODE (Java `RouteEntrySupplier`, .NET `IRouteEntrySupplier`, Python `RouteEntrySupplier` → `List<RouteEntry>`): the programmatic half of the authored side — a route binding a definition/view model/pinned params independently, or a route with NO view model — discovered per backend (a bean in Java, an assembly/module type in the ports). Precedence: `routes.yaml` > code supplier > derived. (Python's `RouteEntry` has no nested `children`: author flat entries with `parent` set) | ✅ | ✅ | ✅ | | [Permissions in YAML](/define/yaml/permissions/) — `access:` on routes (403, nested routes included), app-shell menu items (hidden; a `RouteLink` inherits its route's) and declared actions (not advertised, buttons disabled, 403 if called); `eyesOnly`/`readOnlyUnless`/`disabledUnless` on components; locked fields' client values dropped. Evaluated server-side by the same authorizer as the annotations. Menu items: the ports have no `type: AppShell`, so N/A there; the ports do not read a definition's `actions:`, so a restricted action is refused (403) and its buttons disabled but there is no advertised list to drop it from. No bundle exporter in the ports, so the static-bundle rules are Java-only | ✅ | ✅ | ✅ | | [Translations in YAML](/define/yaml/translations/) — `type: Translations` / `specs/ui/translations/<locale>.yaml`, `${i18n.key}` resolved server-side per request locale (exact → language → fallback → key + one warning), code producer (`TranslationsSupplier` / `ITranslationsSupplier`), authored wins; static bundles resolve in the browser (Java only has a bundle exporter) | ✅ | ✅ | ✅ | | [Environments](/deploy/environments/) — `type: Environment` / `specs/ui/environments/<name>.yaml` overlaying `baseUrl`/`url`/`headers`/`proxy` on the REST source catalogue for `MATEU_ENVIRONMENT`; Java also `-Dmateu.environment` and the bundle goal's `environment` | ✅ | ✅ | ✅ | | Dashboard / Foldout / Welcome / ItemOverview archetypes | ✅ | ✅ | ✅ | | UX components (MetricCard, Gantt, EmptyState, Skeleton…) | ✅ | ✅ | ✅ | | Planning board (tape chart: resources × days, colored blocks, move/select actions) | ✅ | ✅ | ✅ | | High-level UX components (Kanban, Timeline, Stat, Calendar, PricingTable, OrgChart, Heatmap, Funnel, TrendChart, FeatureGrid, Testimonials, Faq, CalloutCard, CommentThread, FileList, ComparisonCard, Checklist, ProgressSteps) | ✅ | ✅ | ✅ | | Front-office components (EntityHeader, Meter, TaskProgress, StatusList, TaskQueue, ResourceGrid, OfferCard incl. toggle state, AddOnPicker, Ledger, PaymentPicker, ProcessMonitor, Notice incl. status/noIcon/content, BulletedList) | ✅ | ✅ | ✅ | | Section polish (`@SeparatorBefore`, text sizes, `@Section(propertyList/frameless)`, responsive zones) | ✅ | ✅ | ✅ | | `Anchor` (external links, `target` + rel=noopener) | ✅ | ✅ | ✅ | | Card menus (`@Menu(display = cards)` / `MenuGroup` / `menu_group`) | ✅ | ✅ | ✅ | | `ActionPanel` (categorised "I want to…" actions) | ✅ | ✅ | ✅ | | `MatrixGrid` (rows × dates, collapsible sections, link/editable cells) | ✅ | ✅ | ✅ | | `RecordMerge` (compare and merge: records side by side, a pick per field, `_merged`/`_choices`) | ✅ | ✅ | ✅ | | App shortcuts + quick-launch codes (`@AppShortcut` → `AppDto.shortcuts`) | ✅ | ✅ | ✅ | | Live header values (`HeaderValuesSupplier`, `UpdateHeaderValue`, `LiveHeaderValues.publish` + `liveUpdates` stream on `/mateu/v3/sse/…`) | ✅ | ✅ | ✅ | | Idle-session warning (`@App(idleTimeoutMinutes…)` → `AppDto.idleSession`, `_keep-alive`) | ✅ | ✅ | ✅ | | `Map` with markers (`MapMarker`, `markerActionId` → `_markerId`; fits the markers when no position) | ✅ | ✅ | ✅ | | Calendar views (`Calendar.view`/`views`: month, week, day, list), per-date cells (`days`), clickable dates (`dayActionId`); `CalendarPage` `views()`/`days()`/`actionOnDay()` | ✅ | ✅ | ✅ | | Access keys mode (`@App(accessKeys)` → `AppDto.accessKeys`) | ✅ | ✅ | ✅ | | Header light/dark switch (`@App(themeToggle)` / `[App(ThemeToggle)]` / `@app(theme_toggle)` → `AppDto.themeToggle`; the Redwood renderer is light only and ignores it) | ✅ | ✅ | ✅ | | [Mobile app](/ux-patterns/mobile-app/) (experimental): the manifest `GET <baseUrl>/mateu/v3/manifest` (Java `@MobileApp` + `mateu.mobile.*` settings, .NET `[MobileApp]`, Python `@mobile_app`; env vars `MATEU_MOBILE_*` everywhere) and "Open on mobile" (`@App(mobileQr)` / `[App(MobileQr)]` / `@app(mobile_qr)` → `AppDto.mobileQr`). The ports have no app logo/favicon/accent, so `icon`/`themeColor` come only from `MobileApp` or the env vars there | ✅ | ✅ | ✅ | | `Popover.trigger` (click/hover) + `@Tooltip("field")` → `GridColumn.tooltipPath` | ✅ | ✅ | ✅ | | `@DragRows` → `CrudlDto.dragType` + `DropZone` | ✅ | ✅ | ✅ | | Row tones (`@RowStatus` → `CrudlDto.rowStatusField`) and listing export buttons on `AutoCrud` | ✅ | ✅ `[RowStatus]` + Export CSV / Excel / PDF (`CsvExportable`/`ExcelExportable`/`PdfExportable` on `Crud<T>`, `Listing<F,R>` or any `ICrudExports` listing; built-in CSV writer, Excel / PDF through the app's `IListingExporter` services — no exporter, no button) | ✅ `RowStatus()` + Export CSV / Excel / PDF (`csv_exportable()` / `excel_exportable()` / `pdf_exportable()`; built-in CSV writer, Excel / PDF through the app's `ListingExporter` subclasses — no exporter, no button, as in Java) | | i18n, events (emit/subscribe), security scaffolding. `[SubscribeTo]` / `@subscribe_to` carry the scopes (`source`/`from`/`condition`, `DOCUMENT` by default) in both ports (conformance case `triggers`). Python has no class-level `read_only_unless` (.NET's `[ReadOnlyUnless]` works on a class) | ✅ | ✅ | 🟡 | | Application context selector (`@AppContext`) | ✅ | ✅ | ✅ | | App header actions (`AppActionsSupplier` → buttons + dropdown groups) | ✅ | ✅ | ✅ | | `@Audience` persona projection (audience app-context + projection filter) | ✅ | ✅ | ✅ | | Capture fields (`@Signature`, `@PhotoCapture`) | ✅ | ✅ | ✅ | | Generic file upload field (`@FileUpload`, accept filter in the field attributes) | ✅ | ✅ | ✅ | | Tree selects (`@TreeSelect` + hierarchical options) | ✅ | ✅ | ✅ | | Smart-search listing filters (enums as multi-select, date/number ranges) | ✅ | ✅ | ✅ | | Declarative listings (`Listing<Row>` + capabilities) | ✅ | ✅ | ✅ | | — typed `DateRange`/`NumberRange`/`Set` filter fields | ✅ | ✅ | ✅ | | — DB pushdown (override `find`: one query, real total, in-memory pipeline skipped) | ✅ | ✅ | ✅ | | Tree lookup selectors (`GridLayout.tree` + `Selector`) | ✅ | ✅ | ✅ | | Lookup fields (`@Lookup` remote combobox + `search-<field>` action) | ✅ | ✅ | ✅ | | — `@Searchable` full selector dialogs (`Selector` + `codesearch`) | ✅ | ✅ | ✅ | | External REST options (`@RestOptions`/`[RestOptions]`/`RestOptions()` → select; options fetched client-side from an arbitrary endpoint via `FormField.optionsSource`) | ✅ | ✅ | ✅ | | External REST listing rows (`@RestListing`/`[RestListing]`/`@rest_listing` on a listing → rows fetched client-side from an arbitrary endpoint via `Crudl.rowsSource`; columns from the Row type) | ✅ | ✅ | ✅ | | External REST button action (`@RestAction`/`[RestAction]`/`@rest_action` on a button → calls an arbitrary endpoint client-side via `Action.restAction`; response toast + merge into form state) | ✅ | ✅ | ✅ | | External REST screen data (`@RestData`/`[RestData]`/`@rest_data` on a view → initial data fetched client-side on load and merged into the form state; reuses the `restAction` machinery via a synthetic `__restdata__` action + OnLoad trigger) | ✅ | ✅ | ✅ | | — Proxy mode (`proxy = true` on any of the four → the fetch is routed through the Mateu server via the reserved `__restfetch__` action: no CORS, and `${secret.X}` auth injected server-side from a secrets provider / `MATEU_SECRET_*` env var; url values percent-encoded by position on both legs; the server resolves the DECLARED source only) | ✅ | ✅ | ✅ | | — Proxy mode for views with no annotation to read (`RestSourceSupplier`: a view assembled at runtime declares its sources programmatically, and they gate `__restfetch__` and resolve a proxy fetch exactly as annotations do) | ✅ | ✅ | ✅ | | [REST source catalogue](/concepts/data-sources/) (`specs/ui/sources.yaml` + `@RestSource`/`RestSourceCatalogSupplier` → a named endpoint referenced by `ref`; two producers, authored wins). Java and .NET carry the registry (catalogue reader + `ref` resolution + `AppDto.restSources`); Python carries it too (`@rest_source` / `RestSourceCatalogSupplier` / `sources.yaml`, `AppMetadata.restSources`, refs resolved server-side for proxy fetches) | ✅ | ✅ | ✅ | | [Action catalogue](/concepts/action-catalogue/) (`specs/ui/actions.yaml` + any `type: Actions` file + `ActionCatalogSupplier` → named client-runnable actions — flows / `restAction` — run by id from the shell menu or any page; two producers, authored wins; owner first, then the catalogue, then the server; non-runnable entries rejected with a warning). `AppDto.actionCatalogue` lowered on all three; a page carries the entries its tree names. .NET (`IActionCatalogSupplier`) and Python (`ActionCatalogSupplier`) have no YAML shell/page `actions:`, so "owner" there is the view's methods; no bundle exporter in the ports | ✅ | ✅ | ✅ | | [Field types](/java-ui-definition/field-types/) (`specs/ui/types.yaml` + `FieldTypeCatalogSupplier` → a named domain type a `FormField`/`GridColumn` references by `fieldType:`; the type's attributes are defaults, the field's own win, unknown → warn + render as declared; `GridColumn.tones` per-value badge tones). Resolved by the Java YAML loader, the browser expander and the .NET/Python YAML loaders (same rule); .NET/Python also add a `[FieldType]`/`FieldType()` marker for listing row fields for listing row classes (a YAML `type: Listing` resolves `fieldType:` on its columns like Java) | ✅ | ✅ | ✅ | | [Sample data on REST sources](/concepts/data-sources/#sample-data-designing-without-an-api) (`sample:`/`sampleFile:`, answered instead of calling the endpoint ONLY in sample mode: visual editor, `-Dmateu.bundle.mock=true` bundles, or an app opted in with `mateu.sources.mock=true`/`MATEU_SOURCES_MOCK=true` → `AppDto.mockSources`; reads get the sample, writes succeed without persisting; proxied and direct legs agree). Renderers: Vaadin/libs, React Native and IntelliJ honour it; .NET/Python short-circuit their proxy leg (no bulk/bundle there) | ✅ | ✅ | ✅ | | [Business components](/java-ui-definition/component-catalogue/) (`specs/ui/components.yaml` + `@BusinessComponent`/`ComponentCatalogSupplier` + `ComponentRef` → a named, BOUND composition of existing pieces referenced by name; ports for free, resolves with no backend). Same two-producers/authored-wins registry as the source catalogue; .NET and Python carry it too (`ComponentRef` expanded server-side, `AppDto.components`; Python `@business_component` / `fluent.ComponentRef`) | ✅ | ✅ | ✅ | | [Custom components](/java-ui-definition/custom-components/) (`CustomComponent(name, props, content)` — a genuinely NEW rendering as data; the per-renderer escape hatch). The WIRE is data and identical across backends; the RENDERING is per-renderer (`registerCustomComponent`, degrading to `<mateu-unsupported>`) | ✅ | ✅ | ✅ | | Sizing intent (`hug`/`fill`/`fixed:<len>` as portable data on the component; a listing infers `fill`) | ✅ | ✅ | ✅ | | Editable grids / inline CRUD editing (`@InlineEditing` + update-row) | ✅ | ✅ | ✅ | | Bulk list actions (`@ListToolbarButton` + typed selection) | ✅ | ✅ | ✅ | | Listing aggregates & grouping (`@Aggregate`/`@GroupBy` + summaries) | ✅ | ✅ | ✅ | | Group header actions (`@GroupAction` buttons on group rows, `_groupValue` parameter; Python `@group_action` + `GroupActionVisibility`) | ✅ | ✅ | ✅ | | Group summaries synthesized for custom `Listing`s (`ListingData.withSynthesizedGroups`) | ✅ | ✅ | ✅ | | Optimistic locking (`@Version` → conflict dialog on save/update-row, `_forceOverwrite`) | ✅ | ✅ | ✅ | | Notification inbox (`NotificationsSupplier` → header bell + `_notifications-*` actions) | ✅ | ✅ | ✅ | | Undoable toasts (`Message.undoable` → undo action id + parameters on the wire) | ✅ | ✅ | ✅ | | Global entity search (`GlobalSearchSupplier` → `globalSearchEnabled` + `_globalsearch`) | ✅ | ✅ | ✅ | | Dialog/Drawer overlays from actions + `closeModal`/`dispatchEvent` (pinned by the `drawer` conformance case). Ports: a `Dialog` cannot be `draggable`/`resizable` or placed (`top`/`left`) | ✅ | 🟡 | 🟡 | | Structure ETag / template-ref (`structureHash` + request `knownStructureHash` → omit the component when unchanged) | ✅ | ✅ | ✅ | | ModelView bindable contract (`__contract__` sync action → fields + actions on `appData._contract`, for the visual-builder tooling) | ✅ | ✅ | ✅ | | Visual-builder live preview (`__preview__` sync action → renders arbitrary YAML page text; the plugin's preview pane) | ✅ | ✅ | ✅ | | YAML validation (`__validate__` sync action → the authoring report on `appData._validation`; MCP `mateu_validate_uidl`) | ✅ | ✅ | ✅ | | MCP authoring plane (resources `mateu://…`, `mateu_list_components` / `get_component_schema` / `validate_uidl` / `preview_uidl`, dev-only `mateu_save_spec`) | ✅ | ✅ | ✅ | | [Live UI push](/reference/agent-operability/#drive-a-live-ui) (`_agent-channel` SSE + pairing code, `mateu_list_sessions` / `mateu_push_ui` / `mateu_dispatch_event`… → `AgentPush` commands; `AppDto.agentPush`; off unless both `mateu.mcp.enabled` and `mateu.mcp.push.enabled`; pinned by `conformance/mcp/push.json`) | ✅ | ✅ | ✅ | | [`layoutDelta:`](/define/yaml/pages/) (what a human changed about the INFERRED layout, anchored to field ids and re-applied every request, so a screen touched in the visual editor keeps following its model). The editor writes it and falls back to a `layout:` snapshot — visibly — when an edit cannot be a delta. Java, .NET and Python apply it (same three rules) | ✅ | ✅ | ✅ | | [Partials](/define/yaml/partials/) (`specs/ui/partials/<ref>.yaml`; spliced into the parent's content, resolved server-side so they never reach the wire). All three splice, stack where there is no list, drop a missing ref and break a cycle; only Java resolves a `ref` that names a class | ✅ | ✅ | ✅ | | YAML pages bound to a ModelView (`specs/ui/<route>.yaml` with `modelView:` → the file supplies the layout, the class supplies state + actions; on the classpath in Java, under the cwd — `MATEU_SPECS_DIR` — in the ports). The ports' YAML component builder covers the whole fluent catalogue generically (the YAML keys are the component's attributes), `Form` pages, partials, `ComponentRef`, a `type: Listing` over a REST source (`rowsSource`/`columns`/`filters`) and a `Button` navigating by `actionable: RouteLink`; `type: AppShell` definitions and a listing's `rowRoute` stay Java-only (the ports author shells in code) | ✅ | 🟡 | 🟡 | | Static-view skip (`@StaticView`/`[StaticView]`/`@static_view` → `staticView` flag; client caches the full response for the session and skips the round-trip on return) | ✅ | ✅ | ✅ | | Sticky sections index (`@Toc`) | ✅ | ✅ | ✅ | | Client-side rules (`@Hidden(expr)`/`@Disabled`/rule supplier) | ✅ | ✅ | ✅ | | Grid form fields + `@OnRowSelected` row-click actions (incl. add/create/select on plain forms outside wizards) | ✅ | ✅ | ✅ | | Fluent `Grid` with column groups (`GridGroupColumn`: a header spanning several columns, its columns in `metadata.columns`; authorable in Java code and in YAML). The ports have no fluent `Grid` component at all — their tables are listings and grid form fields, which have no column groups in any backend — so the group has nothing to live in there | ✅ | N/A | N/A | | Wide-field auto-colspan (grid/textarea/richText span the full row of a multi-column section) | ✅ | ✅ | ✅ | | Inline-editing grid "+" appends an in-place row (the detail-form response targets a container inline grids never render) | ✅ | ✅ | ✅ | | Multi-state embedded islands (`@Inline` orchestrator fields, host-seeded initialData; Python: a field holding a routed view + `Inline()`) | ✅ | ✅ | ✅ | | Multi-column layouts (`@Zones`, `@FoldedLayout`) | ✅ | ✅ | ✅ | | AI chat (`@AI`/`[AI]`/`@ai` → `sseUrl`; the SSE endpoint is developer-provided) | ✅ | ✅ | ✅ | | Semantic (composed) annotations | ✅ | ✅ | ✅ (an `Annotated` alias) | | Federation (remote menus + `MicroFrontend` islands) | ✅ | ✅ | ✅ | | Component adapters | ✅ | ✅ `IComponentAdapter<T>` SPI | ✅ (`ComponentAdapter` + `AdaptedView`) | | Hero search archetype | ✅ | ✅ | ✅ | | Page toolbar from methods (`@Toolbar`, `@ViewToolbarButton`). `@Toolbar` is in both ports (.NET `[Toolbar]`, Python `@toolbar`: label, `buttonStyle`, validation, access gates; conformance case `page-toolbar`). Neither port has `@ViewToolbarButton`: a CRUD record's view page carries the fixed Back to list / Add another / Edit toolbar | ✅ | 🟡 | 🟡 | | Triggers (`@Trigger`: `OnLoad` with `timeoutMillis`/`times`, `OnSuccess`, `OnError`, `OnValueChange` — periodic refresh, chained actions). .NET `[Trigger(TriggerType…)]`, Python `@trigger(TriggerType…)`; the actions they name are advertised and runnable (conformance case `triggers`) | ✅ | ✅ | ✅ | | Class-level `@AutoSave` (debounced save on every change). The ports emit `AutoSave` only from their archetypes (CollectionDetail, GeneralOverview…) | ✅ | — | — | | Editable views (`EditableView` / `AutoEditableView`, `MasterDetailView` orchestrators: a read view with an Edit toolbar that flips to an editor and back) | ✅ | — | — | Import wizard on .NET/Python: same step flow (upload/paste → auto-mapped column grid with a select-editable target-field cell → per-line validation report → typed import + result counts) and the same CSV semantics (`,`/`;` autodetect, RFC-4180-ish quoting, data-URI uploads), on the ports' `[Step(n)]` wizard machinery, and both ports now have the full flow (2026-10-10). On .NET the validation step's forward button is the **Import** completion action, the result step is final (no navigation, a re-sent back/next cannot import twice), steps are named Upload / Mapping / Validation / Result, the heading defaults to `Import <Row>` and `TimeOnly`/`DateTimeOffset`/`Guid` columns convert; its validation surface is DataAnnotations (`[Required]`, `[Range]`…). On Python the import is the wizard's completion action (`@wizard_completion_action("Import")`, Java's `doImport`, then a read-only result step) and its report checks `Required()`, `Min`/`Max`/`Length`/`Pattern` — the same constraints that travel as client-side `validations` and are re-checked when a form is saved. Smart-search filters on .NET/Python: the Crud entity's fields become the same filter widgets (enums → multi-select IN, temporals → date ranges, `[RangeFilter]`/`RangeFilter()` numerics → min–max), applied in-memory over `Fetch()` by default — same as Java's default repository — or pushed to the database by overriding `Find`/`find` (the filters arrive as the raw component state rather than Java's typed `FilterCriterion` objects; a contract difference, not a capability gap). **Recent .NET/Python parity gains (2026-07-17)**: CRUD create/edit in a drawer (`Crud<T>.EditInDrawer` virtual / `@edit_in_drawer` decorator — new and row clicks answer the entity form inside a `Drawer` Add partial over the listing; cancel closes it; save persists and answers `CloseModal` carrying the `mateu-crud:saved-in-drawer` event plus a `RunAction search` command, so the listing refreshes in place with no navigation), the wizard RAIL progress style (`[WizardProgress("rail")]` / `@wizard_progress("rail")` — the step form on the left, a sticky right band with a big `current | total` counter over the vertical step list; `ProgressSteps` carries `vertical` in all three backends), and — closing the day's last gap — the **fluent `FormField` primitive** (a live field composed into any fluent tree, bound to componentState by `fieldId`; with options it renders as a select) plus the `CollectionDetail` and `GeneralOverview` archetypes built on it: tree-supplier views seed their scalar properties into `initialData` (so search/selection round-trip) and emit an `AutoSave` trigger so typing/switching re-renders the page in place. **Recent .NET/Python parity gains (2026-07-11)**: inline CRUD editing (`[InlineEditing]`/`@inline_editing` — editable columns with typed in-place editors + the update-row action rebuilding and saving the row), lookup fields (`[Lookup]`/`Lookup()` → combobox + remoteCoordinates, the handler answers `search-<field>` from the options supplier, filtered and paged), Dialog/Drawer overlays returned from actions (Add partials on the initiator, with `CloseModal`/`DispatchEvent` command factories carrying `{eventName, detail}`), `[Toc]`/`@toc`, the full HeroSearch archetype (hero header + cards listing, starts empty), client-side rules (`[Hidden(expr)]`/`[Disabled]` + `IRuleSupplier`/`RuleSupplier` → `ServerSideComponent.rules`), grid form fields (list-of-rows properties → dataType `array` + stereotype `grid` + columns) with `[OnRowSelected]`/`OnRowSelected()` injecting the clicked row into the handler method, and the `[Zone]`/`@zones` + `[FoldedLayout]`/`@folded_layout` multi-column layouts. Earlier (2026-07-10): CRUD search sorts and paginates; actions can return page banners, a `/route` or a UICommand. Declarative listings (Java `Listing<Row>` + capabilities / Python `Listing[F, R]`) landed the same day with the typed `DateRange`/`NumberRange`/`Set` filters, the `_from`/`_to` state assembly, and the `Selector` contract on top: `@Searchable` fields open their selector listing in a modal (`codesearch-<field>` → Dialog; row pick → value-changed/data-changed/close-modal-requested), including TREE-shaped selectors (`gridLayout()` override → `"tree"`, rows carrying nested `children` arrays). Semantic annotations and the AI chat landed too: .NET resolves composed attributes transitively (`Meta.Find`, attributes decorating attribute classes) while in Python a reusable `Annotated` alias needs no machinery at all; `[AI]`/`@ai` emit `sseUrl` and both manuals document the SSE endpoint contract (POST `{message, sessionId, menuContext?}` → `data:` chunks). The final gaps closed the same day: DB pushdown (`Find`/`find` override — one query with the real total, the in-memory pipeline skipped), federation (`[RemoteMenu]`/`@remote_menu` federated menu entries — the frontend fetches the remote menu itself — and the `MicroFrontend` island component), and component adapters resolved as a documented idiom: both ports render plain classes reflectively, so a thin wrapper view over the foreign object (fields exposing its data, an action writing back) replaces Java's `ComponentAdapter` SPI — see "Adapting foreign classes" in each manual. The four depth tails inside ✅ rows closed too: pre-existing `@Lookup`/`@Searchable` values resolve their display label (`ILookupLabelSupplier`/`LookupLabelSupplier` → `<fieldId>-label` partial data), grid form fields edit in place (`@InlineEditing` on the property, rows binding back into the typed list), permission-driven field states (`@EyesOnly`/`@ReadOnlyUnless`/`@DisabledUnless` against an adapter-supplied Identity), and the full `@App(AUTO)` variant decision table (explicit wins; menu folders via `Group`/`group` → TILES/HAMBURGER_MENU/MENU_ON_TOP; flat menus → TABS). (That closed the feature rows of the time; the component adapters were later given a real SPI in both ports — `IComponentAdapter<T>` / `ComponentAdapter`, 2026-10-10 — and what is still Java-only today is listed in [What is still Java-only](#what-is-still-java-only).) **2026-07-16 parity pass**: the front-office dogfooding wave (OfferCard toggle state, StatusItem avatar, StatusList compact/frameless, Notice status/noIcon/content, `@Audience`) landed on all three backends in the same commits; the two features that had slipped through Java-only — app header actions with dropdown grouping (`AppActionsSupplier`) and `Anchor.target` — were ported the same day (.NET `IAppActionsSupplier`/`Anchor { Target }`, Python `AppActionsSupplier`/`Anchor`), each pinned by golden-JSON tests. The remaining Java-only rows above are in-page orchestration behaviors (embedded islands, inline-grid "+", wide-field auto-colspan), not wire surface. **2026-07-17**: optimistic locking (`[Version]`/`Version()` — stale saves and inline row updates answer the same reload/overwrite conflict dialog as Java, byte-identical texts; `_forceOverwrite` adopts the stored version then bumps) and the notification inbox (`INotificationsSupplier`/`NotificationsSupplier` → `AppMetadata.notificationsEnabled` + `_notifications-list`/`_notifications-read` with ids list or `"all"`) landed on .NET and Python, each pinned by golden-JSON tests mirroring the Java sync suites. ### What the ports closed (2026-10-10) Both ports closed every server row above on 2026-10-10, each pinned by its own tests and the wire by the hard conformance gate: - **.NET**: `IRestSourceSupplier` proxy sources, the source and component catalogues, `layoutDelta:`, group actions and synthesized group summaries, wide-field auto-colspan, the inline-grid "+" row and the whole grid-field row editor, multi-state embedded islands, the `IComponentAdapter<T>` SPI, listing exports (the `IListingExporter` port) and the import wizard's completion action. - **Python**: the same list (`RestSourceSupplier`, `@rest_source`/`sources.yaml`, `@business_component`/`ComponentRef`, `layoutDelta:`, `@group_action`, the grid row editor, embedded islands, `ComponentAdapter`, listing exports (the `ListingExporter` port), `@wizard_completion_action`), plus `Min`/`Max`/`Length` (formerly `Size`)/`Pattern` validation and class- and method-level `@eyes_only`. Proxy mode for views assembled at runtime stays the SSRF-sensitive path on every server: the endpoint is taken from what the server holds (the view's own declarations), never from the request. The shared wire-conformance corpus is a HARD gate on Python: every case must match the Java golden except an explicit, strictly-xfailed allow-list whose every entry is a defect of the golden itself (today none: the Python, .NET and Java runners all run with empty allow-lists). ### What is still Java-only Measured against the generated [wire schema](/reference/wire-specification/#the-machine-readable-schemas) (master after 3.0-alpha.427). The renderers handle all of these; it is the PORTS that cannot produce them. **Wire component types.** The wire registers 116 component types: **114 that a server produces**, plus `Result` and `Stepper`, deprecated for removal since 3.0-alpha.426 (no mapper, record or port produces them; they stay registered until the next wire major). The .NET and Python registries carry 90 of them each (`Element`, `Tooltip`, `ConfirmDialog`, `Details`, `SplitLayout`, `Breadcrumbs`, `Icon` and `Notification` were the last to arrive, pinned by the `generic-components` conformance case); the other 24 producible types are Java-only: | Types | .NET | Python | |---|---|---| | `BoardLayout` (+ `BoardLayoutRow`, `BoardLayoutItem`), `CarouselLayout`, `Chat`, `Container`, `ContextMenu`, `CookieConsent`, `Directory`, `FormEditor`, `FormItem`, `FormSubSection`, `FullWidth`, `Grid` (+ `GridColumn`, `GridGroupColumn` — the ports' tables are listings and grid fields), `MasterDetailLayout`, `MenuBar`, `MessageInput`, `MessageList`, `NotFound`, `Scroller`, `VirtualList`, `Workflow` | — | — | #### Envelope members Members of a type the ports DO emit that neither port ever sets (the same in .NET and Python unless noted). A renderer treats an absent member as its default, so these are features the ports cannot express, not broken screens: | DTO | Java-only members | |---|---| | `AppDto` (25 of 62) | `accentColor`, `accentStrip`, `generatedAccentStrip`, `actions`, `apps`, `askIcon`, `askLabel`, `backLabel`, `backRoute`, `noBreadcrumbs`, `cssClasses`, `style`, `drawerClosed`, `fabs`, `favicon`, `icon`, `logo`, `home`, `homeUriPrefix`, `globalSearchSource`, `notificationsSource`, `notificationsReadSource`, `mcpUrl`, `uploadUrl`, `welcomeMessage` | | `CrudlDto` (26 of 49) | `multipleRowSelectionEnabled`, `onRowSelectionChangedActionId`, `selectionListened`, `hasActionOnSelectedRow`, `useButtonForDetail`, `infiniteScrolling`, `lazyLoading`, `lazyColumnRendering`, `initialPage`, `allRowsVisible`, `contentHeight`, `size`, `header`, `footer`, `child`, `rowRoute` (Java's YAML listings), `showCards`, `wrapCellContent`, `columnBorders`, `columnReorderingAllowed`, `noBorder`, `noRowBorder`, `rowStripes`, `gridStyle`, `vaadinGridCellBackground`, `vaadinGridCellPadding` | | `FormFieldDto` (6 of 43; .NET also lacks `detailPath`, `formStyle`, `formTheme`, `useButtonForDetail`) | `badges`, `bold`, `rightAligned`, `cssClasses`, `mainFilter`, `observed` | | `ActionDto` (8 of 19) | `sse`, `background`, `confirmationTexts`, `js`, `href`, `customEvent`, `modalStyle`, `modalTitle` | | `DialogDto` (4 of 15) | `draggable`, `resizable`, `top`, `left` | #### Authoring Besides the 🟡/— rows of the table: `@ViewToolbarButton`, class-level `@AutoSave`, `@MainFilter`, `@HiddenIn*`, `@Section(sticky, columns, style)`, `@App(layout, backLink, ask…)` and the `EditableView`/`AutoEditableView`/`MasterDetailView` orchestrators have no port equivalent; Python also lacks a class-level `read_only_unless`. (`@Toolbar`, `@Help`, `@Trigger` and `@SubscribeTo(source, from, condition)` are ported — see the table.) ### The conformance gate `conformance/cases/*` (first loads and second requests — an action's messages and commands, an overlay, a rejected save, an error-boundary answer, a wizard's second step, a CRUD's search and new/edit/view forms) must match EXACTLY in Java, .NET and Python, with empty allow-lists. It pins what the ports DO produce; the gaps above are the part of the wire it cannot pin until a port emits it. ### Port idioms: same wire, different declaration The three servers emit the same wire; they do not always declare it the same way. The differences below are **deliberate port idioms** — each language declares the concept the way its developers expect, and the wire (pinned by the conformance corpus) is identical. They are documented here rather than converged, because converging would rename stable port API for no change on screen. The last column says where the review (3.0-alpha.412) did converge, and why. | Concept | Java | .NET | Python | Decision | |---|---|---|---|---| | Menu entries | `@Menu` on a **field** whose type is the target page (`Menu` / `RouteLink` records for submenus and links) | `[MenuItem]` / `[MenuGroup("A/B")]` on **methods** returning the target | `@menu_item` / `@menu_group` on methods | Idiom. A C# property / Python attribute typed as the page would be bound and serialised as form state; a method is the natural "go there" declaration. Same `MenuOptionDto` tree on the wire. | | Header KPI | `@KPI` (no argument; the label comes from the field / `@Label`) on a field or method | `[Kpi("Title")]` (title required) on a property or method | `kpi("Title")` — one lowercase class used both as a method decorator and as an `Annotated[...]` marker | Idiom. The ports carry the label in the declaration because they have no per-member `@Label` on methods; same `KPIDto`. | | Wizard steps | `WizardStep` **fields** of a `Wizard`, in declaration order | `[Step(n)]` on the wizard's properties (1-based) | `Step(n)` marker in `Annotated[...]` | Idiom: named steps in Java, numbered steps in the ports. A step's title (the progress bar's text, the steps/rail bullets) is the step field's label in Java and the `StepTitle(n)` / `step_title(n)` override in the ports. Python's top-level `Step` is that marker; the `ProgressSteps` item (Java/.NET `Step` record) is `mateu_ui.uidl.components.ProgressStep` (the old `components.Step` is deprecated). | | Wizard completion | `@WizardCompletionAction(label, availableFromStep = "stepField")` on a method — the button dispatches the method's name | override `CompletionActionLabel` + `OnNext`, `CompletionAvailableFromStep` (`int?`); the button dispatches `CompletionActionId` (default `next`; set it to Java's method name for an identical wire) | `@wizard_completion_action(label, available_from_step=n)` — the button dispatches the method's name, camelCased | Idiom. `availableFromStep` names a step **field** in Java and a step **number** in the ports, because that is how each one names its steps. | | Wizard progress style | `@WizardProgress(WizardProgressStyle.STEPS)` (enum) | `[WizardProgress("steps")]` | `@wizard_progress("steps")` | Idiom (a string where Java has an enum); values `bar` / `steps` / `rail` everywhere. | | Edit in a drawer | override `Crud.editInDrawer()` | override the `EditInDrawer` property | `@edit_in_drawer` class decorator | Idiom. | | Action timeout / idempotency / shortcut | attributes of `@Action(timeoutMillis, idempotent, shortcut)` | `[ActionOptions(...)]`, `[Shortcut("ctrl+s")]` | `@action_options(...)`, `@shortcut("ctrl+s")` | Idiom: the ports have no `@Action` equivalent, so each knob is its own composable attribute / decorator. | | Toast variants | `NotificationVariant { success, warning, error, primary, contrast }` | `MessageVariant { Success, Info, Warning, Error, Contrast }` | `MessageVariant` (same as .NET) | Idiom; each maps to the wire's variant string. | | Length constraint | Bean Validation `@Size(min, max)` | — (not ported: `[Size]` is the sizing intent) | `Length(min=, max=)` | **Converged (3.0-alpha.412)**: Python's `Size` is now `Length`, because in Java and .NET `Size` is a component's *sizing intent* — the same name meaning two things across ports was a real trap. `Size` still works and warns. | | View-level permission | `@EyesOnly(permissions = …)` on the class | `[EyesOnly(Permissions = …)]` | `@eyes_only(permissions=[…])` | **Converged (3.0-alpha.412)**: the port-only `[Secured("x")]` / `@secured("x")` was silently ignored — nothing read it — so a view "secured" with it was open to everyone. It is now **enforced** with exactly the semantics of `EyesOnly(permissions = "x")` (the view and its actions refused with 403, the menu entries leading to it hidden) and deprecated naming `EyesOnly`. | | Code-authored routes and shells | `RouteEntrySupplier`, `AppSupplier`, `MenuSupplier`, `AppShell` in `mateu-uidl` | `IRouteEntrySupplier`, `IAppSupplier`, `IMenuSupplier`, `AppShell`, `RouteEntry` — **in the `Mateu.Uidl` package since 3.0-alpha.412** (they used to live in `Mateu.Core`) | `RouteEntrySupplier`, `AppSupplier`, `MenuSupplier`, `AppShell` in `mateu_ui.uidl` | **Converged** on the package: a UI-only .NET module can author routes and shells referencing just `Mateu.Uidl`. Their full names stay `Mateu.Core.*` and `Mateu.Core` type-forwards them, so existing code and binaries keep working (a same-named copy in the `Mateu.Uidl` namespace would make every file importing both namespaces ambiguous). | | Global inference switches | `mateu.layout.inference.enabled` / `mateu.page.inference.enabled` (system property or `MATEU_…` env var) | AppContext switches `Mateu.LayoutInference.Enabled` / `Mateu.PageInference.Enabled` | env vars `MATEU_LAYOUT_INFERENCE_ENABLED` / `MATEU_PAGE_INFERENCE_ENABLED` | **Converged (3.0-alpha.412)** on one name and one polarity per switch; the old names keep working with a warning. See [Layout inference](/ux-patterns/layout-inference/#global-switches). | | CollectionDetail composition | a reflected form whose detail is an embedded island (its own `ServerSide` component, round-tripping alone) | a `VerticalLayout` + `ResponsiveGrid` tree built by the archetype | same as .NET | Idiom (2026-10-17 decision). Same screen, same actions (`selectCollectionItem`, `filterCollection`); the ports have no island machinery and nothing on screen needs one. Not a conformance case. | | Crud create/edit form actions | the form's Save/Cancel bubble to the crud MEDIATOR above it (the form advertises `*`) | the form advertises and answers `create`/`save`/`cancel-*` itself | same as .NET | Idiom. The ports have no mediator component above the form; the buttons, labels and outcome are identical. | | Wizard action advertising | a `*` catch-all (the wizard mediator claims every action) | `next` / `back` / `skip` / the completion action, listed | same as .NET | Idiom; the web client dispatches the same ids either way. | | Component route of the root (`""`) | `""` | `_empty` | `_empty` | Idiom; both spellings mean the mount root and every renderer accepts both (the conformance normaliser treats them as equal). | ## Renderers Every renderer speaks the same wire; the depth of widget support varies. Each one is gated in CI against the generated `wire-schema.json` on the 114 produced component types (the two deprecated ones are not required): web (the libs/mateu dispatch test, plus a `RENDERERS` map typed exhaustively over the wire's types, so a missing renderer does not compile), React Native, IntelliJ and Redwood. The gates exercise the real dispatcher or projection with a minimal component of each type and fail on a placeholder — not a string match on the source. | Feature | Vaadin (web) | Redwood (web) | IntelliJ plugin | React Native | |---|---|---|---|---| | Forms, CRUD, navigation | ✅ | ✅ | ✅ | ✅ | | Redwood pattern gaps (2026-10-10): header record/context switcher, `Announce`, hero tone, foldout `summary-N`, crud `preSearch`, a `Drawer` re-sent with an open drawer's id refreshing in place | ✅ shared DS-neutral elements | ✅ oj-sp header data switcher, `dark-<tone>` banner, `oj-sp-foldout-panel` summary slot | ✅ combo + speed search | ✅ bottom-sheet switcher | | Smart-search filter bar (chips, ranges, multi-select) | ✅ | ✅ | ✅ (native panel) | ✅ panel (ranges, multi-select, date pickers) | | Sorting, cards/list/tree layouts, empty states | ✅ | ✅ | ✅ (tree = JTree; cards/list adapt to the table) | ✅ | | Inline editing (@InlineEditing, update-row) | ✅ | ✅ | ✅ (row form) | ✅ (row form) | | Date picker | ✅ | ✅ | ✅ (calendar popup) | ✅ (own calendar) | | Remote lookup select (@Lookup / searchable) | ✅ | ✅ | ✅ | ✅ | | Full field-stereotype set (radio, multiSelect, slider, stepper, stars, color, image upload, money, markdown…) | ✅ | ✅ radio, multi-select, checkboxes, toggle, number/money (`oj-input-number`), textarea, dates, lookups, file/image/signature/photo, slider (`oj-slider`), stars (`oj-rating-gauge`), color, rich text (own editor: HTML, legacy Quill Delta read), markdown/html read-only | ✅ | ✅ | | Client-side rules (visible/disabled/state) + \${...} interpolation | ✅ | ✅ CSP-safe engine (visible/disabled/required/value + `OnValueChange`) on every surface: the page, embedded islands and the open drawer/dialog | ✅ (shared engine) | ✅ (no-eval engine) | | Page banners (@Banner + action-returned) | ✅ | ✅ | ✅ | ✅ | | FABs, header badges, KPIs, charts | ✅ | ✅ header badges, KPIs, `MetricCard`/`Scoreboard` tiles and charts on any page (`oj-chart`: bar, line, area, pie, doughnut, polar, funnel, several series); page and app `@Fab`s stacked above the shell FAB | ✅ (FABs as header buttons) | ✅ | | @AutoSave / @SubscribeTo scopes / @OnRowSelected | ✅ | ✅ | ✅ | ✅ | | Periodic refresh (`OnLoad` with `timeoutMillis` + `OnSuccess` loop, `background`) | ✅ | ✅ (stops when the screen changes) | ✅ (stops when the view changes or its tab closes) | ✅ (stops when the screen changes or unmounts) | | Keyboard shortcuts (`@Action(shortcut)`, `@Tab(shortcut)`) + access keys mode (`@App(accessKeys)`: hold Alt, Alt+letter) | ✅ | ✅ | ✅ (Swing mnemonics) | — (no hardware-key model) | | "Open on mobile" (`mobileQr`: a header button whose dialog shows the QR of the `mateu.io/add` link, a link instead on a phone) | ✅ | ✅ | N/A (desktop IDE) | N/A (it is the app) | | Hover details (`Popover` with `trigger = hover`, `@Tooltip("otherField")` on listing cells) | ✅ | ✅ (shared `oj-popup`) | ✅ | 🟡 press / long-press (no hover on touch) | | Drag rows to a destination (`@DragRows` + `DropZone`: origin and destination in one action) | ✅ | ✅ (`oj-table` dnd) | ✅ | 🟡 "Move to…" picker (no drag on touch) | | AI chat (sseUrl) / theme toggle | ✅ | ✅ AI chat at parity with the web panel (header button + left drawer: streaming, agent progress and tool steps, token usage, markdown answers with in-app links, screen context + projection, `mcpUrl`, `@AI(upload)` attachments, local agent, dictation, wide mode, `render-screen`/navigation events); light only: `@App(themeToggle)` is ignored (no switch) and neither a stored dark choice nor the OS preference applies | ✅ chat (theme = the IDE's own) | ✅ | | [Live UI push](/reference/agent-operability/#drive-a-live-ui) (`@App` `agentPush`: "Connect AI" pairing dialog, the `_agent-channel` stream, agent status, pushed screens/navigation/events) | ✅ | ✅ | ✅ | ✅ | | App context selector | ✅ | ✅ | ✅ (navigator combos) | ✅ | | — searchable picker w/ remote search | ✅ | ✅ | 🟡 loaded options only | ✅ | | Signature capture | ✅ canvas | ✅ canvas (own element: JET has no signature pad) | ✅ mouse canvas | ✅ svg + view-shot | | Photo capture | ✅ getUserMedia | ✅ | 🟡 file picker (no desktop camera API) | ✅ expo-camera | | Tree select dropdown | ✅ | ✅ | ✅ (JTree popup) | ✅ | | Tree lookup selector (dialog) | ✅ | ✅ | ✅ (tree layout) | ✅ (tree layout) | | Custom components (`registerCustomComponent`; unknown → visible placeholder) — the per-renderer escape hatch, each renderer with its own registry + graceful degradation (placeholder + slotted children) | ✅ | ✅ registry (`bridge.registerCustomComponent(name, mount)`) + placeholder and slotted children | ✅ registry (`CustomComponentRegistry.register`) + placeholder and slotted children | ✅ registry (`registerCustomComponent`) + placeholder and slotted children | | Dashboards, Gantt, foldouts, skeletons | ✅ | ✅ foldouts (`oj-sp-foldout-layout`, an `open=false` panel starts as a strip the layout's selection unfolds; collapsible panels inside a tab), dashboards (KPI band, tiles by `colSpan`, `oj-chart`), `Gantt` and `PlanningBoard` on `oj-gantt`, `Skeleton` | ✅ | ✅ | | High-level UX components (Kanban, Timeline, Stat, Calendar… + the front-office set) | ✅ | ✅ every type — Oracle components where they exist (oj-chart funnel, oj-avatar, oj-action-card, oj-rating-gauge, oj-checkboxset, oj-menu-button, oj-collapsible, oj-dialog…), Redwood-token atoms where JET has none (board, timeline, heatmap, org outline, BPMN); see the coverage table below | ✅ | ✅ | | App header actions (buttons + dropdown groups) | ✅ | ✅ | — (sidebar shell, no top bar) | — (drawer shell, no top bar) | | Bulk row selection + selection-required toolbar actions | ✅ | ✅ | ✅ (native multi-select) | ✅ (checkbox column) | | Saved views (named filter sets, default view) | ✅ | ✅ | ✅ (Views menu: apply/save/default/delete, persisted) | 🟡 apply/save/default/delete (session-scoped: kept in memory, reset on app restart) | | Column chooser (per-user show/hide/reorder) | ✅ | ✅ | ✅ (header menu show/hide + native drag-reorder, persisted) | 🟡 show/hide (session-scoped: kept in memory, reset on app restart; no reorder) | | Listing totals footer + group subtotal rows | ✅ | ✅ | ✅ | ✅ | | Column groups (`GridGroupColumn`: a header spanning several columns, in a `Grid`, a listing or a grid field) | ✅ `vaadin-grid-column-group` | ✅ flattened, the group label prefixing its columns (`Occupancy · Adults`: `oj-table` has no grouped headers) | ✅ flattened, `Group · Column` headers (a Swing header is flat) | ✅ flattened, `Group · Column` headers | | Notification bell (inbox, unread count) | ✅ | ✅ (header bell + `oj-popup` with an `oj-list-view`) | ✅ (sidebar popup) | ✅ (drawer row) | | Undoable toasts (Undo button) | ✅ | ✅ (JET `oj-message` with the Undo `oj-button` in its detail slot — `oj-sp-messages-toast` has no actions) | ✅ (balloon action) | ✅ (toast button) | | Entity search (GlobalSearchSupplier: ⌘K palette / search box) | ✅ palette | ✅ the Ask palette: destinations + GlobalSearchSupplier entity results by category | ✅ sidebar search | ✅ drawer search | | Planning board (tape chart) | ✅ drag+select | ✅ `oj-gantt`: move, resize, double click, range selection, hover summary | ✅ drag+select (MouseListener + pure PlanningDrag) | ✅ drag+select (PanResponder + pure planningDrag) | | Session-expiry re-auth + retry (`onSessionExpired`) | ✅ | ✅ | ✅ (SessionGuard, sync re-auth) | ✅ (sessionGuard, retry once) | | Card menus (`@Menu(display = cards)`: a group opening as a panel of cards) | ✅ | ✅ (`oj-popup`) | ✅ | ✅ | | Action panel ("I want to…": categorised actions, show more, hide unpopulated, shortcut) | ✅ | ✅ (`oj-dialog` + `oj-switch`) | ✅ (dialog; IDE keymap wins on a shared shortcut) | ✅ (modal; no keyboard shortcut) | | Matrix grid (rows × dates, collapsible sections, link cells, in-place editing) | ✅ | ✅ (`oj-data-grid`) | ✅ (`JBTable` + row header) | ✅ | | Compare and merge records (`RecordMerge`) | ✅ | ✅ | ✅ (Swing grid, a button group per row) | ✅ (one card per field) | | App shortcuts (`@AppShortcut`), `?` list, quick-launch codes | ✅ (⌘K palette + command center) | ✅ (Ask palette) | ✅ (view key bindings, dialog, "Go to code…") | 🟡 codes only (drawer field; no hardware keys) | | Live header values + `liveUpdates` stream (one per browser, tabs share it) | ✅ | ✅ | ✅ (navigator; one stream per session) | ✅ (drawer; foreground only, `expo/fetch`) | | Idle-session warning (countdown, stay / sign out, activity shared across tabs) | ✅ | ✅ | ✅ (IDE activity; one session) | ✅ (touches; background counts as idle) | | Row tones (`@RowStatus`) | ✅ | ✅ | — | — | | Dockable multi-tab workspace | — | — | ✅ (IDE editor tabs/splits) | — | | App registry boot (installable → registry → backend) | — | — | ✅ (+ min IDE build gate) | ✅ | ### Redwood component coverage What the Redwood/VB renderer does with each component type of the wire. A type it does not render shows a visible "Unsupported component" placeholder (its children, if it is a container, still render), so this table — not the feature rows above — is the authority on what Redwood paints.  Generated from `frontend/web/monorepo/apps/redwood/poc/coverage.mjs` and checked in CI against the wire catalogue and the renderer's code (`node poc/parity-check.mjs`): 96 rendered, 11 layout containers, 2 partial, 0 not rendered. A type the renderer does not know (one added to the wire later) shows a visible "Unsupported component" placeholder, like the web renderers, and its children still render. | Component | Redwood | How | |---|---|---| | `AccordionLayout` | ✅ | oj-collapsible per panel | | `ActionPanel` | ✅ | oj-dialog + oj-switch ("I want to…") | | `AddOnPicker` | ✅ | | | `Anchor` | ✅ | link / file download | | `App` | ✅ | oj-sp shell: navigation drawer / top tabs / card menus | | `Avatar` | ✅ | oj-avatar | | `AvatarGroup` | ✅ | oj-avatar per person, +N beyond maxItemsVisible | | `Badge` | ✅ | oj-badge classes | | `Bpmn` | ✅ | an SVG drawn from its BPMN-DI (or laid out by its flows): bpmn-js is not under a permissive licence | | `Breadcrumbs` | ✅ | a breadcrumb nav in the content (the shell keeps its own trail) | | `BulletedList` | ✅ | | | `Button` | ✅ | oj-button | | `Calendar` | ✅ | month, week, day and list views (JET has no calendar: a Redwood-token grid, oj-buttonset-one switcher), per-date cells, clickable dates | | `CalloutCard` | ✅ | oj-panel band with its theme, icon and CTA oj-button | | `Card` | ✅ | oj-panel | | `CarouselLayout` | ✅ | an image gallery is an oj-film-strip; other slides one at a time with a ‹ › pager and dots (client-side) | | `Chart` | ✅ | oj-chart: bar, line, pie, doughnut, radar/polar area, scatter; several series | | `Chat` | ✅ | an inline conversation streamed from its sseUrl (poc/chat.mjs); the app-level assistant is the shell panel | | `Checklist` | ✅ | oj-checkboxset per item (sends {_item, _done}) + oj-progress-bar | | `CommentThread` | ✅ | replies indented under their comment, oj-avatar per author | | `ComparisonCard` | ✅ | oj-panel: both values and the delta with its trend | | `ConfirmDialog` | ✅ | oj-dialog, open while its openedCondition holds; Confirm / Reject / Cancel send their actions | | `ContextMenu` | ✅ | its content, then an oj-menu-button with the menu; a right click on the content opens it too | | `CookieConsent` | ✅ | a band fixed to the top/bottom; hidden once its cookie exists, dismissing sets it | | `Crud` | ✅ | oj-table + smart search; groups, totals, tones, columns, saved views, export | | `CustomComponent` | ✅ | a registry the app fills (bridge.registerCustomComponent); without a view, a visible placeholder + its children — same contract as the web | | `DashboardLayout` | ✅ | oj-flex columns, each panel its colSpan | | `DashboardPanel` | ✅ | oj-panel tile (title, subtitle, content) | | `Details` | ✅ | oj-collapsible (client-side state) | | `Dialog` | ✅ | oj-dialog (overlay stack) | | `Directory` | ✅ | a column per group with its links (in-app routes navigate inside the shell) | | `Drawer` | ✅ | oj-drawer-popup (overlay stack), subtitle, footer actions | | `DropZone` | ✅ | drop target for @DragRows listing rows (oj-table dnd); its content as text lines | | `Element` | ✅ | third-party web component, events wired back; a REMOTE screen's root-relative import loads from the remote's origin | | `EmptyState` | ✅ | oj-sp-empty-state: the page-level one, and any other in the content with its call to action | | `EntityHeader` | ✅ | projected to the page header (sticky business card); a fact with an action gets its icon button after the value | | `Faq` | ✅ | oj-collapsible per question (client-side state), the answer as Markdown | | `FeatureGrid` | ✅ | oj-panel / oj-action-card tiles on an oj-flex grid of its columns | | `FileList` | ✅ | a row per file: icon by type, download link, size · type, its action | | `FoldoutLayout` | ✅ | oj-sp-foldout-layout (an open=false panel starts as a strip the layout selection unfolds); inside a tab, collapsible panels | | `Form` | ✅ | oj-form-layout | | `FormField` | ✅ | oj-input-*, oj-select-*, oj-radioset, oj-checkboxset, oj-input-number, capture fields | | `FormLayout` | ✅ | oj-form-layout | | `Funnel` | ✅ | oj-chart type funnel | | `Gantt` | ✅ | oj-gantt: a row per task, progress fill, task click → onTaskSelectionActionId | | `Grid` | ✅ | oj-table (list display): tree rows with disclosure, client-side paging by its size | | `Heatmap` | ✅ | JET has none: a calendar heatmap (a column per week), 4 levels + legend, values on hover | | `HeroSection` | ✅ | the Welcome archetype: oj-sp-header-welcome-banner; in the content, a hero band (title, subtitle, background image) over its children | | `HorizontalLayout` | ✅ | oj-flex row | | `Icon` | ✅ | the Redwood icon font (oj-ux-ico-*), an emoji as text | | `Image` | ✅ | JET has no image component: an <img>; relative sources are served by the backend | | `Kanban` | ✅ | JET has no board: oj-panel columns, cards as oj-action-card when they act (_clickedCard) | | `Ledger` | ✅ | | | `Map` | ✅ | Leaflet + OSM tiles (JET has no street map): markers, fit, markerActionId | | `Markdown` | ✅ | formatted (headings, lists, quotes, code, tables, bold, italics, links, allowed inline HTML) as allowlist-sanitized HTML | | `MasterDetailLayout` | ✅ | list + detail panes | | `MatrixGrid` | ✅ | oj-data-grid | | `MenuBar` | ✅ | oj-buttons, links and oj-menu-buttons for submenus | | `MessageInput` | ✅ | oj-input-text + Send oj-button; Enter or Send sends {message} | | `MessageList` | ✅ | oj-avatar + name, time and text per message | | `Meter` | ✅ | oj-progress-bar | | `MetricCard` | ✅ | KPI tile: value, trend, drill-in action | | `MicroFrontend` | ✅ | loaded from its baseUrl into a surface of its own and painted in place; its actions go back to it | | `NotFound` | ✅ | | | `Notice` | ✅ | oj-sp-message-banner style band + actions | | `Notification` | ✅ | an info band (title — text); action messages show as toasts | | `OfferCard` | ✅ | | | `OrgChart` | ✅ | the tree as an indented outline (VB templates cannot recurse) with oj-avatar; nodes with an action are oj-action-cards (_clickedNode) | | `Page` | ✅ | oj-sp header (title, subtitle, KPIs, toolbar, banners, status badge, peer arrows, timestamp; overline + title placeholder drawn over it) | | `PaymentPicker` | ✅ | | | `PlanningBoard` | ✅ | oj-gantt (move, resize, double click, range selection) | | `Popover` | ✅ | trigger + the content WITH its structure (headings, lists, links, badges, markdown) as sanitised HTML in a shared oj-popup (hover/focus or click) | | `PricingTable` | ✅ | oj-panel plans (the featured one highlighted), CTA oj-button | | `ProcessMonitor` | ✅ | a row per process: systems, ok/warning/error badges, status, action | | `ProgressBar` | ✅ | oj-progress-bar (value or the state at valueKey, indeterminate); a wizard shows its progress as the guided process | | `ProgressSteps` | ✅ | oj-train | | `RecordMerge` | ✅ | compare & merge: a table of radios per field (differences highlighted), oj-switch «only differences», result summary, merge button | | `ResourceGrid` | ✅ | | | `ResponsiveGrid` | ✅ | fixed tracks → oj-flex columns by their fr weights and spans; auto-fill/auto-fit → as many per row as fit at each breakpoint; reorderable tiles drag (and Alt+←/→) | | `Result` | ✅ | oj-panel with the icon of its type, message, links and the what-next action | | `Scoreboard` | ✅ | KPI band | | `Separator` | ✅ | | | `Skeleton` | ✅ | the shell skeleton bones (JET has no skeleton), text/card/grid/form × count | | `SplitLayout` | ✅ | two panes | | `Stat` | ✅ | | | `StatusList` | ✅ | | | `Stepper` | ✅ | a numbered step header per child, its content below | | `TabLayout` | ✅ | oj-tab-bar (nested strips flattened) | | `TaskProgress` | ✅ | | | `TaskQueue` | ✅ | | | `Testimonials` | ✅ | oj-panel quotes, oj-avatar, oj-rating-gauge (read only) | | `Text` | ✅ | | | `Timeline` | ✅ | oj-timeline is deprecated: a Redwood list with markers, items with an action as borderless oj-buttons (_clickedItem) | | `Tooltip` | ✅ | the wrapped component keeps its view; the text opens in the shared oj-popup on hover/focus (on the button itself, or an info marker) | | `TrendChart` | ✅ | oj-chart line/area | | `VirtualList` | ✅ | every item through the same projection (no windowing — neither has the neutral web renderer) | | `BoardLayout` | ✅ layout | children stacked, not a board | | `Container` | ✅ layout | | | `ContentLayout` | ✅ layout | | | `CustomField` | ✅ layout | its component in place | | `Div` | ✅ layout | | | `FormItem` | ✅ layout | | | `FormSection` | ✅ layout | | | `FormSubSection` | ✅ layout | | | `FullWidth` | ✅ layout | | | `Scroller` | ✅ layout | | | `VerticalLayout` | ✅ layout | | | `FormEditor` | 🟡 | read only: the defined form previewed with the real field widgets; the web designer edits it | | `Workflow` | 🟡 | read only: the definition as a numbered flow of steps; the web designer edits it | | `AccordionPanel` | ↳ | of AccordionLayout | | `BoardLayoutItem` | ↳ | of BoardLayout | | `BoardLayoutRow` | ↳ | of BoardLayout | | `FormRow` | ↳ | of FormLayout | | `GridColumn` | ↳ | of Grid / Crud | | `GridGroupColumn` | ↳ | of Grid / Crud: oj-table has no grouped headers, so the group label prefixes its columns ("Occupancy · Adults") | | `Tab` | ↳ | of TabLayout |  ### React Native component coverage What the React Native renderer (iOS / Android, `frontend/app/react-native`) does with each component type of the wire. Since 2026-10-10 **every** type has a native renderer — CI fails the build if a new wire type is added without one (`scripts/parity-check.mjs`), so a screen never shows "Unsupported component" on a phone. 🟡 marks a deliberate mobile adaptation (no hover or right-click on touch → press / long-press; diagram editors shown read-only).  Generated from `frontend/app/react-native/scripts/coverage.mjs` and checked in CI against the wire catalogue and the renderer's switch (`node scripts/parity-check.mjs`): every wire type has a native renderer — 90 rendered, 11 layout containers, 6 parts of another component, 9 with a documented mobile adaptation. None is dropped. | Component | React Native | How | |---|---|---| | `AccordionLayout` | ✅ | | | `ActionPanel` | ✅ | modal; no keyboard shortcut | | `AddOnPicker` | ✅ | | | `Anchor` | ✅ | in-app route or OS browser | | `App` | ✅ | drawer / tabs shell (AppRenderer); nested App = own island at its home route | | `Avatar` | ✅ | image or initials | | `AvatarGroup` | ✅ | overlapping, +N overflow | | `Badge` | ✅ | | | `Breadcrumbs` | ✅ | | | `BulletedList` | ✅ | | | `Button` | ✅ | | | `Calendar` | ✅ | month / week / day / list | | `CalloutCard` | ✅ | | | `Card` | ✅ | | | `CarouselLayout` | ✅ | paging swipe, dots, prev/next, auto-advance, loop | | `Chart` | ✅ | | | `Chat` | ✅ | opens the assistant panel (same contract as the app chat FAB) | | `Checklist` | ✅ | | | `CommentThread` | ✅ | | | `ComparisonCard` | ✅ | | | `ConfirmDialog` | ✅ | | | `ContentLayout` | ✅ | main / aside / footer; aside beside main ≥ 768 px, stacked on a phone | | `CookieConsent` | ✅ | dismissible banner, dismissal persisted on the device | | `Crud` | ✅ | table / list / cards / tree, smart-search panel, selection, totals, groups, inline edit, saved views | | `CustomComponent` | ✅ | registry (registerCustomComponent); unregistered → a visible placeholder that still renders the slotted children | | `DashboardLayout` | ✅ | | | `DashboardPanel` | ✅ | | | `Details` | ✅ | collapsible panel | | `Dialog` | ✅ | overlay fragments open as a modal sheet | | `Directory` | ✅ | | | `Drawer` | ✅ | overlay fragments open as a modal sheet; a Drawer in the tree is drawn in place | | `EmptyState` | ✅ | | | `EntityHeader` | ✅ | a fact with an action gets a tappable icon after its value | | `Faq` | ✅ | | | `FeatureGrid` | ✅ | | | `FileList` | ✅ | | | `FoldoutLayout` | ✅ | overview card + accordion of panels | | `Form` | ✅ | | | `FormField` | ✅ | every stereotype, date picker, lookups, capture fields | | `FormSection` | ✅ | | | `FormSubSection` | ✅ | | | `Funnel` | ✅ | | | `Gantt` | ✅ | | | `Grid` | ✅ | horizontal-scroll table, tree rows indented, action cells | | `Heatmap` | ✅ | | | `HeroSection` | ✅ | | | `Image` | ✅ | | | `Kanban` | ✅ | | | `Ledger` | ✅ | | | `Map` | ✅ | | | `Markdown` | ✅ | | | `MasterDetailLayout` | ✅ | side by side ≥ 768 px, stacked on a phone | | `MatrixGrid` | ✅ | | | `MenuBar` | ✅ | horizontal strip; submenus as an action sheet | | `MessageInput` | ✅ | | | `MessageList` | ✅ | | | `Meter` | ✅ | | | `MetricCard` | ✅ | | | `MicroFrontend` | ✅ | own island (own session when it has its own baseUrl) | | `NotFound` | ✅ | | | `Notice` | ✅ | | | `Notification` | ✅ | inline status strip | | `OfferCard` | ✅ | | | `OrgChart` | ✅ | | | `Page` | ✅ | header (title, subtitle, badges, KPIs, toolbar, banners), FABs | | `PaymentPicker` | ✅ | | | `PlanningBoard` | ✅ | drag + select (PanResponder) | | `PricingTable` | ✅ | | | `ProcessMonitor` | ✅ | | | `ProgressBar` | ✅ | | | `ProgressSteps` | ✅ | vertical by design | | `RecordMerge` | ✅ | one card per field (records as rows of radios) | | `ResourceGrid` | ✅ | | | `ResponsiveGrid` | ✅ | declared tracks + col spans; stacks below stackBelow (600 px default) | | `Result` | ✅ | icon by result type, links, next step | | `Scoreboard` | ✅ | | | `Separator` | ✅ | | | `Skeleton` | ✅ | | | `SplitLayout` | ✅ | | | `Stat` | ✅ | | | `StatusList` | ✅ | | | `Stepper` | ✅ | children as numbered steps | | `TabLayout` | ✅ | | | `TaskProgress` | ✅ | | | `TaskQueue` | ✅ | | | `Testimonials` | ✅ | | | `Text` | ✅ | | | `Timeline` | ✅ | | | `TrendChart` | ✅ | | | `VirtualList` | ✅ | | | `BoardLayout` | ✅ container | | | `Container` | ✅ container | | | `CustomField` | ✅ container | its component in place | | `Div` | ✅ container | | | `FormItem` | ✅ container | | | `FormLayout` | ✅ container | | | `FormRow` | ✅ container | | | `FullWidth` | ✅ container | | | `HorizontalLayout` | ✅ container | | | `Scroller` | ✅ container | | | `VerticalLayout` | ✅ container | | | `Bpmn` | 🟡 | read-only diagram (react-native-svg, from the BPMN DI section); edit on the web | | `ContextMenu` | 🟡 | long-press (no right-click on touch) opens an action sheet | | `DropZone` | 🟡 | "Move to…" picker (no drag on touch) | | `Element` | 🟡 | HTML tags map to native text / image / rule, on.click runs its action; custom elements (web components) show their text content | | `FormEditor` | 🟡 | read-only definition preview; edit on the web | | `Icon` | 🟡 | emoji / glyphs and common icon names; other design-system icons show a dot | | `Popover` | 🟡 | opens on press (no hover on touch) | | `Tooltip` | 🟡 | long-press shows it (no hover on touch); also the accessibility hint | | `Workflow` | 🟡 | read-only layered diagram; edit on the web | | `AccordionPanel` | ✅ part | of AccordionLayout | | `BoardLayoutItem` | ✅ part | of BoardLayout | | `BoardLayoutRow` | ✅ part | of BoardLayout (items side by side ≥ 768 px) | | `GridColumn` | ✅ part | of Grid / Crud | | `GridGroupColumn` | ✅ part | of Grid / Crud: its columns, headed "Group · Column" | | `Tab` | ✅ part | of TabLayout |  ### IntelliJ plugin component coverage The IntelliJ plugin has a case for **every** wire component type in `ComponentMetadataDto` (115 as of 2026-10-10). This is enforced, not just claimed: `WireTypeParityTest` reads the backend's `@JsonSubTypes` list and fails the plugin build when a type has no branch in `ui/ComponentRenderer.kt`, and `WireTypeRenderTest` renders each of them headlessly and checks for exceptions, the "Unsupported component" fallback and accessible names on every control. The types below were the last to arrive, so this is how each one maps to Swing: | Wire type | IntelliJ rendering | |---|---| | `Grid` / `GridColumn` | `JBTable` over the page rows (read-only); a stray column shows its header | | `GridGroupColumn` | a Swing header is flat: the group's columns are table columns headed `Group · Column` (in a Grid, a Crud and a grid field) | | `VirtualList` | `JBList`, one line per row | | `MasterDetailLayout` | `Splitter` (master / detail) | | `CarouselLayout` | one slide at a time, ‹ › buttons and `n / total` | | `BoardLayout` / `BoardLayoutRow` / `BoardLayoutItem` | rows stacked, equal-width columns | | `ContentLayout` | `main-*` centre, `aside-*` start/end column (`asideWidth`), `footer-*` below | | `ResponsiveGrid` | grid with the column count of `gridTemplateColumns` | | `FormItem`, `Tab`, `AccordionPanel`, `Stepper` met outside their container | a row / titled group / stack of their children | | `Breadcrumbs` / `Breadcrumb` | link trail, current item in bold | | `MenuBar` | row of buttons; groups open a popup menu (submenus nest) | | `ContextMenu` | the wrapped component with a popup (right click, or left click when asked) | | `Directory` | sitemap of links under group headings | | `Avatar` / `AvatarGroup` | round initials badge (name as tooltip and accessible name); `+N` overflow | | `Icon` | the platform icon for known names, else the name | | `Details` | disclosure toggle (▸/▾) over its content | | `Tooltip` | tooltip + accessible description on the wrapped component | | `Notification`, `Result`, `NotFound` | inline strip / outcome page with links / not-found page with a way back | | `CookieConsent` | dismissible strip (the IDE has no cookies; dismissal lasts the session) | | `Element` | the element as HTML text; an `on.click` runs its action | | `Bpmn` | the process as an ordered list of its named flow nodes (start → tasks → end) | | `Workflow`, `FormEditor` | their value, read-only and monospaced | | `Chat`, `MessageList`, `MessageInput` | inline assistant (mateu-chat SSE, with the project's token), message list, input + Send (`{message}`) | | `Dialog`, `Drawer` met inline | opened as the usual overlay window, once per id | | `ConfirmDialog` | modal confirm / reject / cancel when `openedCondition` holds | | `MicroFrontend` | an embedded island with its own context; another origin gets its own session **without** the project's token | Since 2026-07-12 (DS-native rule) the non-Vaadin web renderers render crud layouts (table/list/cards/masterDetail/tree), toolbar buttons and grid-stereotype form fields with their OWN design-system components, and since 2026-07-16 the shells render the app header actions (plain buttons + dropdown groups) with their own widgets too. MessageList/MessageInput (Vaadin): as of 2026-07-10 these carry a real data model (`List<MessageListItem>` / an `actionId` that fires on submit) — they were previously stubs that rendered hardcoded demo data. **Retired renderers (2026-08-12 reconciliation).** SAP UI5, Redwood-OJ (OJET), Red Hat/PatternFly and SLDS were **retired**, and their `apps/sapui5`, `apps/redhat` and `apps/slds` directories have since been deleted. They had a column here long after they stopped existing — which is the worst failure mode for this page, since a matrix that promises a renderer nobody can use is worse than one that admits a gap. **The supported web renderers are Vaadin and the Redwood/VB line.** `frontend/app/vscode-extension` is **not** a renderer: it hosts the visual editor (the same web bundle the IntelliJ JCEF host runs), so it belongs with the tooling, not in this table. **Authoring tooling.** The IntelliJ plugin (renderer, visual editor, specs/ui schema validation, binding checks, **New | Mateu** file templates, per-project settings with bearer/OIDC authentication) and the VS Code extension (the same visual editor bundle, `yamlValidation` for `specs/ui/**`, **Mateu: New File…** with the same skeletons) are supported tooling. The Figma design-to-code pipeline remains *preview*: it is not covered by the support promise above. **Fetch-plan edges (known renderer gaps).** The client-side fetch plan (`optionsSource`, `rowsSource`, `restAction`, `restData` — see [the renderer contract](/design-systems/renderer-contract/)) is honoured with two edges: - **Multi-value `optionsSource`.** Vaadin resolves `optionsSource` on a single-select field (the common reference case — a record pointing at one other entity). A **multi-value** field (`multiSelect`/`listBox`/`combobox` — a record pointing at *many*) reads static `options` or a remote `search-<field>` action, not `optionsSource`; a one-to-many reference to an external catalogue is not wired yet. It spans three widget branches and is deliberately deferred rather than half-wired. - **VB/Redwood REST sources.** Since 2026-10-10 the Redwood/VB core (`poc/restSources.mjs`) consumes the catalogue like the web: listing `rowsSource`, field `optionsSource`, route `data:` and `restAction`s, resolved by `ref` against `AppDto.restSources` / the bundle manifest, direct or proxied (`__restfetch__`), with sample data under the same opt-in rule and column `tones`. Its `${…}` interpolation covers dotted paths only, not the web's full expression language. Update this page whenever parity moves — it is referenced from the language manuals and the [Rosetta](/reference/language-rosetta/). --- # Prompt-to-app (AI authoring) URL: https://mateu.io/reference/prompt-to-app/ > An LLM writes a Mateu UI as DATA and the output is checked mechanically against Mateu's published JSON Schemas, with a repair loop — the authoring half of AI-native, distinct from operating an app over MCP. :::caution[Spike / direction — not GA] This is a **proof of concept**, deliberately small. It proves the *mechanism*; it is not a productized prompt-to-app builder. See [Limits](#limits-honest) below. For the production-ready half — an agent **operating** an existing app — see [Agent operability (MCP)](/reference/agent-operability/). ::: There are two ways an LLM meets a Mateu app, and they are **different things**: | | Who defines the UI | What the LLM does | |---|---|---| | **[Operate](/reference/agent-operability/)** (MCP) | a developer (the Mateu definition) | reads/writes data + runs actions + navigates, over MCP | | **Author** (this page) | **the LLM** | **writes the UI definition (UIDL)** as data | This page is the second one: **the LLM writes the UIDL.** ## Why this is different from "AI generates React" On Mateu the UI is **data**, and Mateu **publishes JSON Schemas** for that data (`backend/shared/uidl/*-schema.json`, the same files editors point IntelliSense at). So an LLM's output is a **small definition that is verifiable against a contract** — a wrong shape is caught and repaired, not shipped as thousands of lines of unreviewable imperative code. That is the whole thesis: the AI produces *reviewable, schema-valid data*, and the framework (tested once) supplies the behaviour, a11y, i18n and security. The volume that makes AI-generated frontends a liability never exists. ## How it works ``` prompt ──▶ LLM ──▶ extract JSON ──▶ validate against the PUBLISHED schema (ajv) │ valid ──▶ done ✅ │ invalid ─▶ send the errors back ──▶ (repeat, bounded) ``` The harness lives in `frontend/prompt-to-app/`: | Module | Role | |---|---| | `schemas.mjs` | Loads a published schema by name (`specs` \| `uidl` \| `routes` \| `sources` \| `mount`) straight from `backend/shared/uidl` — so it validates against exactly what Mateu ships. | | `validate.mjs` | `ajv` over that draft-07 schema → `{ valid, errors[] }`. | | `generate.mjs` | `generateDefinition(prompt, { llm, schemaName, maxAttempts })` — the repair loop. The **LLM is injected**. | | `llm.mjs` | `anthropicLlm()` (the real, pluggable edge) + `scriptedLlm()` (tests). | The **LLM is a parameter**, not baked in: the loop takes an `llm(messages, { system }) => Promise<string>` function. That is what makes the mechanism testable without a key — and what lets you point it at *any* model, including an existing Mateu AI agent (see below). ## Run it ```bash cd frontend/prompt-to-app npm install # generate against a real model (Anthropic): ANTHROPIC_API_KEY=… node index.mjs --schema routes \ "an app with a bookings list and a customers list" # verify the harness with no key — scripted LLM + the REAL published schemas: npm test ``` Example — the model authors a `routes.yaml` (as JSON) and it passes the published `routes-schema.json`: ```json { "type": "Routes", "routes": [ { "route": "bookings", "layout": "bookings" }, { "route": "customers", "layout": "customers" } ] } ``` ## Verified live with a real LLM The harness is not tied to a specific provider — its `llm` is injected. Pointed at a **real Mateu AI agent** (an SSE endpoint) as the backend, the prompt *"create a routes file with two screens"* returned exactly the definition above, **valid against the published `routes-schema.json` on the first attempt** — the LLM *authoring* UIDL, not operating an app. `live-ecdemo-probe.mjs` in the same folder is the probe used (it folds the system prompt + schema into the agent's single message and keeps the plain-text reply). ## Limits (honest) {#limits-honest} - **The LLM call is the only unverified part** in the tests — the loop is exercised with a scripted LLM and the **real** published schemas; `npm test` never calls an API. - **Schema-shape only.** Mateu's schemas are an OPEN lower bound (no `additionalProperties: false`), so this catches wrong types / missing required fields, **not** "unknown component" or semantic errors. A stronger check would round-trip the definition through the real loader (renders → valid); that is the natural next step, not done here. - **The full schema is inlined in the prompt** — fine for `routes`/`sources`; the `uidl`/`specs` schemas are ~130 KB, so a real tool would trim or retrieve. - Emits **JSON**; a `routes.yaml`/`type: UI` author would convert to YAML (1:1). See `frontend/prompt-to-app/README.md` for the full module reference. --- # Stability & versioning URL: https://mateu.io/reference/stability-and-versioning/ > What counts as Mateu's public API, how versions are numbered, how long a deprecated API stays, and the compatibility rules of the wire. From the **3.0 beta** on, Mateu commits to the rules on this page. Before it — the 3.0 alphas — the API changed in place; [Migrating from alpha](/reference/migrating-from-alpha/) lists everything that did. ## Version numbers - Releases are tagged `vMAJOR.MINOR[-qualifier.N]` and published to Maven Central under `io.mateu`, every artifact named `mateu-*` (`mateu-uidl`, `mateu-mvc`, `mateu-vaadin`…; the pre-beta ids are relocation poms — see [Migrating from alpha](/reference/migrating-from-alpha/#maven-artifacts)), with the tag's version (`3.0-alpha.406`, `3.0-beta.1`, `3.0.0`, `3.1.0`…). Every module of one release shares that version — never mix versions of `io.mateu` artifacts in one app. - **Major** (`3` → `4`): may break the public API or the wire. Announced in advance, with a migration guide. - **Minor** (`3.0` → `3.1`): new features; **no breaking change** to the public API or the wire. May deprecate. - **Patch** (`3.0.0` → `3.0.1`): fixes only. - **Pre-releases** (`-alpha.N`, `-beta.N`): alphas may break anything; betas follow the deprecation policy below, except for fixes to defaults that were a security problem. ### What "beta" means The first beta freezes the public surface listed under [What is public API](#what-is-public-api). From that tag on: - **Stable API changes only through deprecation.** A replacement is added, the old element is marked deprecated (naming the replacement) and **both work side by side for at least one release** — deprecated in `3.0-beta.N`, removable in `3.0-beta.N+1` at the earliest; once `3.0.0` is out, the one-minor rule below applies. Nothing stable is renamed in place. - **Experimental API can change** in any beta (and later in any minor) — that is what the marker is for. The [list below](#stable-and-experimental-api-by-package) is the exact boundary. - The **wire** stays additive within `wireVersion` 3.x (see [Wire compatibility](#wire-compatibility)), and YAML keys follow the same add-then-deprecate rule as Java names. - **The promise is enforced by the build**, not only stated: from `3.0-beta.1` on, an incompatible change to the stable API fails CI in all three backends — Java (japicmp), .NET (the pinned public surface of `Mateu.Uidl`) and Python (the pinned exports and signatures of `mateu_ui.uidl`). See [Enforcement](#enforcement). ## What is public API You can build on these; they follow the deprecation policy. | Surface | Where it lives | |---|---| | **The authoring API** — annotations (`@UI`, `@Action`, `@Section`…), interfaces (`CrudStore`, `Listing` and its capability interfaces, suppliers…), the fluent component records and data types | the `io.mateu:mateu-uidl` artifact (`io.mateu.uidl.*`) | | **The archetypes and orchestrators** you extend — `AutoCrud`, `FilteredAutoCrud`, `Crud`, `Wizard`, `Dashboard`, `Foldout`, `HeroSearch`, `CollectionDetail`, … | their `public`/`protected` members in `io.mateu:mateu-core` (`io.mateu.core.infra.declarative.orchestrators.*`) | | **The wire** — the JSON exchanged between backend and renderer | the [wire specification](/reference/wire-specification/), versioned by `wireVersion`, its fields pinned by the generated `wire-schema.json`; compatibility rules [below](#wire-compatibility). The Java DTO classes of `io.mateu:mateu-dtos` that model it are **not** under the Java binary-compatibility promise — see [The wire DTOs](#the-wire-dtos-json-not-java-binaries) | | **The authoring schemas** — `uidl-schema.json`, `routes-schema.json`, `sources-schema.json`, `specs-schema.json` (YAML `specs/ui/**`) | `backend/shared/uidl/*.json`, generated from the records | | **The HTTP contract** — `POST {baseUrl}/mateu/v3/…` | the [wire specification](/reference/wire-specification/) | | **Build integration** — annotation processor coordinates and options, `mateu-bundle-maven-plugin` goals and parameters | their Maven coordinates | | **Adapter configuration** — the `mateu.*` properties the guides document (`mateu.cors.allowed-origins`, `mateu.ui.modules`…) and `@EnableMateuUiModules` (Spring MVC / WebFlux) | the adapter artifacts (`mateu-mvc`, `mateu-webflux`, …); everything else in them is internal | | **The .NET and Python authoring APIs** — `Mateu.Uidl` attributes/types, `mateu_ui.uidl` (and `mateu_ui.uidl.components`) decorators/markers/components | the `Mateu.Uidl` NuGet package and the `mateu-ui` PyPI package; same policy, pinned by their own tests ([Enforcement](#enforcement)) | ### The wire DTOs: JSON, not Java binaries `mateu-dtos` is public — you can read it, and a renderer or a non-Java producer can build on the JSON it describes — but **its contract is the JSON wire, not the Java classes**. The wire is versioned by `wireVersion` and stays additive within a major ([Wire compatibility](#wire-compatibility)); the Java records that model it are not covered by the binary-compatibility promise: - a new optional wire field adds a component to its DTO record, which replaces the record's canonical constructor — harmless for the JSON, binary-incompatible for Java code that called that constructor; - so build DTOs through their **builders** (`AppDto.builder()…`), or better, don't build them at all: hand Mateu the authoring API (`mateu-uidl`) and let it map. The compatibility check still compares `mateu-dtos` against the last release and publishes the report, but it never fails the build for it, even with enforcement on. Deprecations in `mateu-dtos` (an enum constant that is no longer sent, an unreachable DTO) still follow the deprecation policy. ### Module layering The three public modules depend on each other in one direction only, and a test (`LayeringTest` in `mateu-uidl`) keeps it that way: - **`mateu-dtos`** — the wire — depends on nothing Mateu. A renderer or a non-Java producer can read it without the authoring API. - **`mateu-uidl`** — the authoring API — depends on `mateu-dtos` only through a closed set of *wire-boundary* types: the escape hatches that hand Mateu a ready-made wire object (`DtoSupplier`, `MapsToDto`, `CardRow`), the request as received (`HttpRequest.runActionRq()` / `getUiRq()`, used by `SearchableSelection`) and the long-task stream (`LongTask`, `ProgressReporter`). Everything else in `mateu-uidl` is wire-agnostic; a new import of `io.mateu.dtos` outside that list fails the build. It never depends on `mateu-core`. - **`mateu-core`** depends on both, and maps the one onto the other. An app module that only declares UIs needs `mateu-uidl` (which brings `mateu-dtos` along for those boundary types); it never needs `mateu-core` at compile time. ### Imports: names shared by two packages Several concepts exist both as an **annotation** and as a **fluent record** — `@Badge` on a field and `new Badge(…)` in a component tree — so the same simple name lives in two packages. With two star imports the bare name is ambiguous and does not compile. Java's rule settles it: **a single-type import always wins over a star import.** Star-import the package you use most and import the other type explicitly: ```java import io.mateu.uidl.annotations.*; // @Section, @Toolbar, @Badge… import io.mateu.uidl.data.*; import io.mateu.uidl.data.Badge; // the record wins for the bare name `Badge`… class Example { @io.mateu.uidl.annotations.Badge boolean active; // …and the annotation is written qualified Badge chip; // the record } ``` The shared names (pinned by `NameCollisionsTest` in `mateu-uidl`, so a new one is a reviewed decision): | Packages | Names | |---|---| | `annotations` / `data` | `Avatar`, `Badge`, `Breadcrumb`, `Breadcrumbs`, `BulletedList`, `Button`, `Details`, `FormLayout`, `Icon`, `KPI`, `Menu`, `Notice`, `RestAction`, `Rule`, `Status`, `Tab`, `Text`, `Tooltip`, `Validation` | | `annotations` / `fluent` | `Action`, `Trigger`, `UI` | | `annotations` / `interfaces` | `App`, `Filterable`, `Searchable` | | `fluent` / `interfaces` | `Listing` (the fluent listing component / the listing contract) | | `data` / `interfaces` | `Page` (a page of rows / the routed-page marker) | | `data` / `fluent` | `Step` | | with `java.util` | `List` (`@List`), `Map`, `Calendar` — with `import java.util.*` also star-imported, import `java.util.List`/`Map` explicitly | **Not public** — may change in any release, without deprecation: - anything under `io.mateu.core` other than the archetypes above (mappers, use cases, resolvers, `infra.*` internals), the adapters' internals (`mateu-mvc`, `mateu-webflux`, …) and the **generated** controllers and resolvers; - the renderers' JavaScript/TypeScript internals (`libs/mateu`, `apps/*`) — the contract with a renderer is the wire, not the code; - anything marked `@Deprecated(forRemoval = true)` or `@Experimental` (see below), or "experimental" or "internal" in its Javadoc or in these docs; - anything marked **`@io.mateu.uidl.annotations.Internal`** — types and members that are `public` only because Mateu's own modules call them across packages (request plumbing such as `HttpRequest.storeRunActionRqDto`, the wire dispatch hooks of `Listing`/`Crud`, the import wizard's built-in steps…). The compatibility check skips them like experimental API; they are listed [below](#stable-and-experimental-api-by-package). Do not call or override them; - log messages and the text of framework-generated error messages. ## Experimental API Some public surfaces are still being shaped. They are marked with **`@io.mateu.uidl.annotations.Experimental`** (on a type — which covers all its members — or on a single member), and the rule for them is: > **`@Experimental` API may change or be removed in a minor release**, without the one-minor > deprecation period below. Everything else in the public API follows the deprecation policy. The API compatibility check (see [Enforcement](#enforcement)) skips anything carrying the annotation. When an experimental API is promoted, the annotation is removed in a minor release and the CHANGELOG says so; from then on it is stable. Experimental today: | Surface | Where | |---|---| | The **AI assistant** chat panel and its MCP wiring | `@AI`, the `Chat` component (`io.mateu.uidl`); the MCP endpoint (`POST /mateu/mcp`, off by default) and the tool projection it serves; the `agent-cli` modules (not published) | | The **new YAML authoring catalogues** | field types (`types.yaml`: `FieldTypeEntry`, `FieldTypeCatalog`, `FieldTypeCatalogSupplier`, `GridColumn.tones`), translations (`Translations`, `TranslationsSupplier`), environments (`Environment`), YAML access keys (`Access`), the project descriptor (`ProjectSettings`, `ProjectRenderer`) and sample data on REST sources (`RestDataSource.sample`, `RestSourceEntry.sample`) — the YAML shapes and the Java types behind them | | **Development tooling** | live reload (dev mode, `/mateu/dev/*`), the Redwood embedded `<mateu-ui>` JET component | | The **Figma design-to-code pipeline** | the contract packaged at `META-INF/mateu/contract.json` in the uidl jar, the Figma plugin and the modux importer/codegen | | The **pattern-gap and PMS-parity features** of `3.0-alpha.409` — weeks old, not yet proven in production | the archetype display options (`Toggle`, `CrudDisplay`, `WizardDisplay`, `GeneralOverviewDisplay`), wizard drafts and navigation hooks (`Draftable`, `stepSkippable`, `beforeStepNavigate`, `@WizardCompletionAction(availableFromStep)`), the record switcher (`RecordSwitcher`, `RecordSwitcherSupplier`), docked panels (`DockedPanel`), the `@Section` affordances (`editAction`/`addAction`/`viewMoreAction`), hero tones, screen-reader announcements (`UICommand.announce`), pre-search content, the action panel, the matrix grid, map markers, drag rows to a drop zone, access keys, card menus, calendar views, hover popovers and cell tooltips, row tones, reorderable dashboards and the shared action catalogue (`actions.yaml`, `ActionCatalog`) | The exact list, type by type, is [generated from the code](#stable-and-experimental-api-by-package). ### Stable and experimental API, by package Everything public in these packages is **stable** unless it is listed as experimental or internal here or is deprecated. The table and the lists are generated from the `@Experimental` / `@Deprecated` / `@Internal` markers in the sources (by `ApiStabilityListTest` in `mateu-uidl`, which fails the build when this page is stale), so they are exactly what the compatibility check enforces. The .NET (`Mateu.Uidl`) and Python (`mateu_ui.uidl`) ports follow the same boundary for the same concepts.   | Module | Package | Public types | Stable | Experimental | Deprecated | Internal | |---|---|---:|---:|---:|---:|---:| | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators` | 3 | 2 | 0 | 0 | 1 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.calendar` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.collectiondetail` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.crud` | 13 | 4 | 0 | 0 | 9 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.crud.actionhandlers` | 12 | 0 | 0 | 0 | 12 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.crud.routeresolvers` | 7 | 0 | 0 | 0 | 7 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.dashboard` | 3 | 1 | 0 | 0 | 2 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.datamanagement` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.editableview` | 2 | 2 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.foldout` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.ganttpage` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.generaloverview` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.herosearch` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.importwizard` | 8 | 1 | 0 | 0 | 7 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.itemoverview` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.masterdetail` | 2 | 1 | 0 | 0 | 1 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.smartsearch` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.todolist` | 1 | 1 | 0 | 0 | 0 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.welcome` | 3 | 1 | 0 | 0 | 2 | | `mateu-core (archetypes)` | `io.mateu.core.infra.declarative.orchestrators.wizard` | 2 | 2 | 0 | 0 | 0 | | `mateu-dtos` | `io.mateu.dtos` | 277 | 247 | 0 | 30 | 0 | | `mateu-uidl` | `io.mateu.uidl` | 7 | 5 | 1 | 0 | 1 | | `mateu-uidl` | `io.mateu.uidl.annotations` | 174 | 163 | 7 | 4 | 0 | | `mateu-uidl` | `io.mateu.uidl.data` | 315 | 263 | 46 | 6 | 0 | | `mateu-uidl` | `io.mateu.uidl.di` | 2 | 2 | 0 | 0 | 0 | | `mateu-uidl` | `io.mateu.uidl.fluent` | 34 | 31 | 0 | 3 | 0 | | `mateu-uidl` | `io.mateu.uidl.interfaces` | 109 | 92 | 8 | 2 | 7 | | `mateu-uidl` | `io.mateu.uidl.layout` | 3 | 0 | 0 | 0 | 3 | | `mateu-uidl` | `io.mateu.uidl.reflection` | 3 | 0 | 0 | 0 | 3 | | `mateu-uidl` | `io.mateu.uidl.security` | 2 | 2 | 0 | 0 | 0 | | **Total** | | **991** | **829** | **62** | **45** | **55** | **Experimental types** (the whole type and its members): - `io.mateu.uidl`: `LiveHeaderValues` - `io.mateu.uidl.annotations`: `AI`, `AppShortcut`, `AppShortcuts`, `DragRows`, `MobileApp`, `RowStatus`, `Tooltip` - `io.mateu.uidl.data`: `Access`, `ActionCatalog`, `ActionPanel`, `ActionPanelCategory`, `ActionPanelItem`, `Announcement`, `AppContextSelector`, `AppGlobalSearchSource`, `AppNotificationsSource`, `AppShortcutEntry`, `CalendarDay`, `CalendarView`, `Chat`, `CrudDisplay`, `DockedPanel`, `Document`, `DocumentDisposition`, `DropZone`, `Environment`, `FieldTypeCatalog`, `FieldTypeEntry`, `GeneralOverviewDisplay`, `HeaderValue`, `HeroTone`, `MapMarker`, `MatrixCell`, `MatrixColumn`, `MatrixGrid`, `MatrixRow`, `MatrixSection`, `MenuDisplay`, `MenuPresentation`, `MergeField`, `MergeRecord`, `NotFound`, `PageFab`, `PageSetup`, `PopoverTrigger`, `ProjectRenderer`, `ProjectSettings`, `RecordMerge`, `RecordSwitcher`, `SwitcherType`, `Toggle`, `Translations`, `WizardDisplay` - `io.mateu.uidl.interfaces`: `ActionCatalogSupplier`, `DocumentRenderer`, `Draftable`, `FieldTypeCatalogSupplier`, `HeaderValuesSupplier`, `KeepAliveHandler`, `RecordSwitcherSupplier`, `TranslationsSupplier` **Experimental members** of otherwise stable types: - `io.mateu.core.infra.declarative.orchestrators.calendar.CalendarPage`: `actionOnDay`, `days`, `daysClickable`, `openCalendarDay`, `switchCalendarView`, `views` - `io.mateu.core.infra.declarative.orchestrators.crud.Crud`: `display`, `nextIdAfter`, `saveAndNextLabel` - `io.mateu.core.infra.declarative.orchestrators.dashboard.Dashboard`: `reorderable` - `io.mateu.core.infra.declarative.orchestrators.datamanagement.DataManagement`: `bottomPanel`, `endPanel`, `toggleBottomPanel`, `toggleEndPanel` - `io.mateu.core.infra.declarative.orchestrators.foldout.Foldout`: `panelSummary` - `io.mateu.core.infra.declarative.orchestrators.generaloverview.GeneralOverview`: `display`, `info`, `infoWidth` - `io.mateu.core.infra.declarative.orchestrators.smartsearch.SmartSearchPage`: `preSearchContent` - `io.mateu.core.infra.declarative.orchestrators.welcome.Welcome`: `heroTone` - `io.mateu.core.infra.declarative.orchestrators.wizard.Wizard`: `beforeStepNavigate`, `display`, `stepSkippable` - `io.mateu.uidl.annotations.App`: `accessKeys`, `idleSignOutUrl`, `idleTimeoutMinutes`, `idleWarningSeconds`, `liveUpdates`, `mobileQr` - `io.mateu.uidl.annotations.Menu`: `display`, `image` - `io.mateu.uidl.annotations.Section`: `addAction`, `editAction`, `viewMoreAction` - `io.mateu.uidl.annotations.WelcomeBanner`: `tone` - `io.mateu.uidl.annotations.WizardCompletionAction`: `availableFromStep` - `io.mateu.uidl.data.AppHeaderAction`: `route` - `io.mateu.uidl.data.Calendar`: `dayActionId`, `days`, `view`, `views` - `io.mateu.uidl.data.CalendarEvent`: `endDate`, `endTime`, `startTime` - `io.mateu.uidl.data.FieldLink`: `presentation` - `io.mateu.uidl.data.FoldoutPanel`: `summary` - `io.mateu.uidl.data.GridColumn`: `tones` - `io.mateu.uidl.data.HeroSection`: `tone` - `io.mateu.uidl.data.Map`: `attribution`, `markerActionId`, `markers`, `tileUrl` - `io.mateu.uidl.data.Menu`: `presentation` - `io.mateu.uidl.data.MetricCard`: `timeframe` - `io.mateu.uidl.data.PlanningBlock`: `icon`, `summary` - `io.mateu.uidl.data.PlanningBoard`: `attributeColumns`, `openActionId`, `rangeSelectActionId`, `resizeActionId` - `io.mateu.uidl.data.PlanningResource`: `attributes`, `icon` - `io.mateu.uidl.data.Popover`: `trigger` - `io.mateu.uidl.data.RecordSwitcher`: `actionId`, `optionsSource`, `route` - `io.mateu.uidl.data.ResponsiveGrid`: `asReorderable`, `reorderable` - `io.mateu.uidl.data.RestDataSource`: `sample` - `io.mateu.uidl.data.RestSourceEntry`: `sample` - `io.mateu.uidl.data.RouteEntry`: `access` - `io.mateu.uidl.data.RouteLink`: `presentation` - `io.mateu.uidl.data.UICommand`: `announce`, `announceAssertive`, `print`, `updateHeaderValue` - `io.mateu.uidl.fluent.AppShell`: `accessKeys`, `contextSelectors`, `globalSearch`, `headerActions`, `headerValues`, `idleSignOutUrl`, `idleTimeoutMinutes`, `idleWarningSeconds`, `liveUpdates`, `mobileQr`, `notifications`, `shortcuts` - `io.mateu.uidl.fluent.Form`: `badges`, `banners`, `fabs`, `kpis`, `overline`, `peerNav`, `recordSwitcher`, `timestamp`, `titlePlaceholder` - `io.mateu.uidl.fluent.Listing`: `dragType`, `preSearch`, `rowStatusField` - `io.mateu.uidl.interfaces.Actionable`: `presentation` **Internal members** of otherwise stable types (`@Internal`: framework plumbing, outside the promise — do not call or override them): - `io.mateu.core.infra.declarative.orchestrators.crud.Crud`: `addButtonsToList`, `behaviourSource`, `getStyleForList`, `isListingRoute`, `list`, `metadataSource`, `stateSource` - `io.mateu.core.infra.declarative.orchestrators.wizard.Wizard`: `currentStepField` - `io.mateu.uidl.LiveHeaderValues`: `reset`, `subscribe` - `io.mateu.uidl.di.MateuBeanProvider`: `setBeanProvider` - `io.mateu.uidl.interfaces.HttpRequest`: `storeGetUIRqDto`, `storeRunActionRqDto` - `io.mateu.uidl.interfaces.Listing`: `getCrudId`, `handleActionOnRow`  The **Internal** column counts types that are `public` only because Java has no module-private: the reflection helpers in `io.mateu.uidl.reflection`, the layout heuristics in `io.mateu.uidl.layout`, `IconConverter` (Jackson plumbing of `IconKey`) and `RoutedClassProvider` (implemented by the code the annotation processors generate), and the machinery behind the archetypes in core — the CRUD `actionhandlers` / `routeresolvers` packages, the `*Composer` and `Inferred*` bridges, `CapabilityCrud`, `CrudAdapterHelper`, `FilterCriteriaBuilder`, `ListingSummarySpec` and `SearchableValues`. They are not part of the promise, the compatibility check skips them, and they may change in any release. The extension points you *implement* — `InstanceFactory`, `RouteResolver` / `RouteValue` / `CompiledRouteValue`, `BeanProvider` — are stable. ## Deprecation policy - An API is **deprecated for at least one minor release before it is removed** — e.g. deprecated in `3.1`, removable in `3.2` at the earliest. Removal only in a minor or major, never in a patch. - A deprecation always names its replacement (`@Deprecated` + `@deprecated use … instead` in Javadoc, the `[Obsolete]` message in .NET, a `DeprecationWarning` in Python) and is listed in the [CHANGELOG](https://github.com/miguelperezcolom/mateu/blob/master/CHANGELOG.md). - Where a rename can be bridged, the old name keeps working as an alias for the deprecation period. - A **default that changes behaviour** is treated like a removal: announced one minor ahead, with a switch to keep the old behaviour for at least that minor. Security fixes are the exception: an insecure default can change in a patch, and the release notes say how to opt back in. ## Enforcement **The 3.x public API is frozen from `3.0-beta.1` on**, and the build enforces it in every backend. An incompatible change to a stable element fails the pull request's checks (the `backend-tests` and `python` jobs) and tells you how to make it compatible instead: **add + deprecate** — add the replacement next to the old element, keep the old one working and mark it deprecated naming the replacement, and remove it no earlier than the release the [deprecation policy](#deprecation-policy) allows. | Backend | What is checked | How | Accepting a deliberate change | |---|---|---|---| | **Java** | `mateu-uidl` and the archetype packages of `mateu-core` (`io.mateu.core.infra.declarative.orchestrators.*`), binary **and** source compatibility; `mateu-dtos` report-only ([why](#the-wire-dtos-json-not-java-binaries)) | [japicmp](https://siom79.github.io/japicmp/) in `mvn verify` (so also `install`) against `<mateu.japicmp.baseline>` in `backend/pom.xml` — a release Maven Central serves, moved forward after each release by the release workflow's "Point the examples at …" pull request (`scripts/bump-example-version.sh`) | a reviewed entry in `backend/api-compat/japicmp-exclusions.properties` | | **.NET** | `Mateu.Uidl`: every exported type name and every public/protected member signature (constructors with their defaults, methods, properties incl. `init`, fields, events, enum members); `Mateu.Core` / `Mateu.AspNetCore`: exported type names | `PublicSurfaceTests` against `backend/dotnet/test/Mateu.Tests/api/*.txt` | rerun with `MATEU_API_WRITE=true` and commit the rewritten file | | **Python** | `mateu_ui.uidl`, `mateu_ui.uidl.components`, `mateu_ui.core`, `mateu_ui.fastapi`: the exported names; `mateu_ui.uidl` and `.components`: the parameters (name, kind, has-a-default) of every decorator, function and constructor, the public methods of every class and the members of every enum | `test_api_freeze.py` / `test_public_surface.py` against `backend/python/tests/api/public-exports.json` / `public-signatures.json` | rerun with `MATEU_API_WRITE=true` and commit the rewritten file | In .NET and Python an **addition** also fails until it is re-pinned — it is compatible, but the review should see every change to the surface. A removed or changed member is reported separately as a break of the promise. ### Java: how the check works `mvn verify` compares the `mateu-uidl` jar and the archetype packages of `core` — and, report-only, the `mateu-dtos` jar — against `<mateu.japicmp.baseline>` (in `backend/pom.xml`; `scripts/bump-example-version.sh` moves it to each release once it is on Maven Central) and writes a report to `target/japicmp/api-compatibility.{md,html,diff}` of each module; CI publishes it in the job summary. - It is **enforcing by default** (`<mateu.api.enforce>true</mateu.api.enforce>`; the plugin's own `mateu.japicmp.enforce` follows it). A binary- or source-incompatible change to the **non-`@Experimental`, non-`@Internal`** surface of `mateu-uidl` and the archetypes fails the build with the list of breaks and the add + deprecate recipe (`backend/api-compat/api-guard-enforce-true.groovy`, japicmp's post-analysis script): ```text Incompatible change to the FROZEN 3.x public API (compared with <mateu.japicmp.baseline> in backend/pom.xml): - io.mateu.core.infra.declarative.orchestrators.dashboard.Dashboard#columns(): METHOD_REMOVED Within 3.x a stable element is never removed, renamed or re-typed in place. Do ADD + DEPRECATE instead: 1. add the replacement next to the old element … ``` - Typical compatible spellings: a new **overload** instead of a changed parameter list; a new **default** method on an interface instead of an abstract one (`METHOD_ADDED_TO_INTERFACE` is a break for implementers); a new record component through a **new constructor**, keeping the old canonical one delegating to it; a new type instead of a renamed one, the old one deprecated. - **`backend/api-compat/japicmp-exclusions.properties`** is the reviewed allowlist: adding an entry is how an intentional break (the end of a deprecation period, a major release) gets through; the comment block above the list names the release or PR that accepted each group, and the list is reset to its sentinel whenever the baseline moves. The [Internal](#stable-and-experimental-api-by-package) types are excluded from the check. - Marking an existing stable API `@Experimental` or `@Internal` is itself reported as a removal — japicmp drops the annotated element on the new side only — so an API cannot leave the promise silently: such a mark needs an allowlist entry until the baseline moves past it. - **Locally**: `mvn verify -pl shared/uidl` (or `shared/core`). `-Dmateu.api.enforce=false` makes it report-only, to read the full japicmp report of a break (a failing run stops before writing it); `-Dmateu.japicmp.skip=true` skips it, e.g. offline — the baseline jar comes from Maven Central. Neither is for a pull request: CI runs the default. Until the beta the check was report-only — the alphas changed the API in place, and [Migrating from alpha](/reference/migrating-from-alpha/) is the record of it. ## Wire compatibility The wire is versioned separately from the artifacts: every response carries `wireVersion` (currently `3.0`). The normative rules are in the [wire specification](/reference/wire-specification/#status-and-versioning); in short: - **Additive within a wire major.** A minor Mateu release may add optional fields, new component types and new commands. It never removes a field, changes its type or changes its meaning. - **Consumers must be tolerant**: ignore unknown fields, render unknown component types as a placeholder and keep going. Every first-party renderer does; a custom renderer must too. - **Consumers check the major.** The web (Vaadin) and Redwood renderers, React Native and the IntelliJ plugin compare the response's `wireVersion` with the major they were built for: the same major is fine whatever the minor; another major shows the user a clear message ("This app's server speaks Mateu wire 4.x; this renderer supports 3.x") once, instead of a broken screen. The wire major only changes with a Mateu major. - **Producers must be conservative**: a backend never requires a field a renderer of the same wire major might not send. - A backend and a renderer of the **same wire major** interoperate. In practice: keep the backend and the renderer artifact on the same Mateu release (they ship together), and the .NET and Python backends speak the same wire as the Java one of the same release. - The [conformance corpus](/reference/wire-specification/#conformance) is the executable definition of "wire-equivalent": a change that makes it fail is a breaking change. ## Schemas and YAML The authoring schemas are generated from the records and checked by a test, so they always match the code of their release. Within a major, a key may be **added**; a key is only removed or renamed through the deprecation policy. A YAML file valid against one release's schema stays valid in the next minor. ## Supported versions Which releases get bug and security fixes, and which Java, .NET, Python, framework and IDE versions a release supports, is the [Support policy](/reference/support-policy/). How to report a vulnerability is in [SECURITY.md](https://github.com/miguelperezcolom/mateu/blob/master/SECURITY.md). --- # Support policy URL: https://mateu.io/reference/support-policy/ > Which Mateu versions get bug and security fixes, which Java, .NET, Python, framework, IDE and device versions are supported, and how to report a vulnerability. This page says which releases receive fixes and which platforms a release supports. What may change between releases — public API, deprecation, the wire — is in [Stability & versioning](/reference/stability-and-versioning/); the limitations of the current release are in [Known issues](/reference/known-issues/). ## Which versions get fixes | Line | Bug fixes | Security fixes | |---|---|---| | **Latest minor of 3.x** (`3.N`) | ✅ in patch releases `3.N.x` | ✅ | | **Previous minor** (`3.N-1`) | ❌ — upgrade to the latest minor | ✅ critical and high severity, for **6 months** after `3.N` is released | | Older 3.x minors | ❌ | ❌ | | **3.0 pre-releases** (`-alpha.N`, `-beta.N`) | only in the next pre-release | only in the next pre-release | | 1.x / 2.x | ❌ | ❌ | - **Pre-releases.** Until `3.0.0` is out, fixes ship only in the next beta: there are no patch releases of a beta. Alphas are not supported — upgrade with [Migrating from alpha](/reference/migrating-from-alpha/). - **A minor is a safe upgrade.** A minor release never breaks the public API or the wire (see [Stability & versioning](/reference/stability-and-versioning/)), so the fix for a bug in an older minor is the upgrade. - **Next major.** When `4.0` is released, the last `3.x` minor receives security fixes for **12 months**. - **One version per app.** Every `io.mateu` artifact, the .NET packages, the Python wheel and the renderers of one release share one version number; a fix is released for all of them at once. Never mix versions in one app (use the `io.mateu:mateu-bom`). ## Supported platforms What a release is built and tested against. A version outside these ranges may work, but a problem that only reproduces there is not treated as a bug. ### Servers | Platform | Supported | Tested in CI | |---|---|---| | **Java** | 21 or later (the artifacts are compiled for Java 21) | 21 | | Spring Boot (MVC and WebFlux) | 4.x — **Spring Boot 3 is not supported** | 4.1 | | Quarkus | 3.x | 3.40 | | Micronaut | 4.x | 4.10 | | Helidon MP | 4.x | 4.5 | | Build tool | Maven 3.9+ or Gradle 8+ | Maven 3.9 | | **.NET** (`Mateu.*` packages, ASP.NET Core) | `net8.0` and `net10.0` | both | | **Python** (`mateu-ui` on PyPI, FastAPI) | 3.11 or later; FastAPI ≥ 0.110, Pydantic 2 (≥ 2.6), PyYAML ≥ 6 | 3.11, 3.12, 3.13, and the lowest declared dependency versions | The supported range of a runtime follows its vendor: when Microsoft ends support for a .NET version, or Python for a Python version, Mateu drops it in the next minor and says so in the CHANGELOG. .NET 8 reaches its end of support on 10 November 2026. ### Renderers and tools | Platform | Supported | |---|---| | **Web renderers** (Vaadin, Redwood) | current versions of Chrome, Edge, Firefox and Safari (desktop, and Safari on iOS / Chrome on Android). The Redwood renderer loads Oracle JET from Oracle's CDN, so the browser must reach it | | **React Native app** | iOS and Android as supported by Expo SDK 57 (React Native 0.86) | | **IntelliJ plugin** | IntelliJ IDEA 2025.2 and 2025.3 (builds `252`–`253.*`). The range is raised once the JetBrains plugin verifier passes on the next line | | **VS Code extension** | VS Code 1.85 or later | | **Node.js** | not needed to *use* Mateu — the renderers ship pre-built inside their jars. Building the renderers, the docs or the e2e suite from source needs Node 24 | ## Reporting a problem - **Bugs and questions:** [GitHub issues](https://github.com/miguelperezcolom/mateu/issues) and [Discord](https://discord.gg/YFb9utDMYK). Say which Mateu version, server (Java adapter, .NET or Python) and renderer you use; a minimal `@UI` class or YAML file that reproduces it is ideal. - **Security vulnerabilities:** never in a public issue. Report them privately through GitHub's [private vulnerability reporting](https://github.com/miguelperezcolom/mateu/security/advisories/new), as described in [SECURITY.md](https://github.com/miguelperezcolom/mateu/blob/master/SECURITY.md), which also states the response times (acknowledgement within 3 business days, a fix for critical and high severity within 30 days of the assessment). ## Software bill of materials Every framework release attaches CycloneDX SBOMs (JSON) to its [GitHub release](https://github.com/miguelperezcolom/mateu/releases): one for the Maven artifacts, one for the web renderer bundle (the production npm dependencies of the Vaadin renderer and the shared client library), one for the Python wheel and one for the .NET packages. Use them to check a release against your vulnerability scanner or licence policy. The dependency advisories that cannot be fixed by upgrading are listed with their reasons in [SECURITY-DEPENDENCIES.md](https://github.com/miguelperezcolom/mateu/blob/master/SECURITY-DEPENDENCIES.md). --- # Useful types URL: https://mateu.io/reference/useful-types/ These public types are not the core DSL by themselves, but they appear often enough that they deserve documentation. --- ## Messages and browser commands ### `Message` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Represents user-facing feedback. ```java return new Message("Saved successfully"); ``` Useful for notifications and success/error messages. ### `UICommand` Represents commands executed in the browser. Examples: ```java UICommand.navigateTo("/users"); UICommand.runAction("refresh"); UICommand.pushStateToHistory("/users?page=2"); ``` This is one of the key primitives for browser-side effects. ### `UICommandType` Important values include: - `NavigateTo` - `RunAction` - `PushStateToHistory` - `CloseModal` - `SetWindowTitle` - `SetFavicon` - `AddContentToHead` - `AddContentToBody` --- ## Forms and fields ### `FormField` Core fluent representation of a field. Contains: - data type - stereotype - required / readOnly - options - remote coordinates - detail path - editor/create forms - layout details This is one of the most important low-level types in the fluent DSL. ### `FieldDataType` Important values include: - `string` - `integer` - `number` - `date` - `time` - `dateTime` - `bool` - `array` - `file` - `status` - `money` - `component` - `menu` - `range` - `action` - `actionGroup` - `dateRange` ### `FieldStereotype` This is the key enum behind `@Stereotype` / `@Representation`. It defines the rendering type for a field. --- ## Grids and listings ### `GridColumn` Defines a column in a grid/listing. Contains things like: - id - label - data type - stereotype - alignment - sorting - filtering - width - text/action behavior ### `GridContent` Base interface for fluent grid content. ### `GridGroupColumn` Groups multiple grid columns together. --- ## Relationships and options ### `Option` Represents a selectable option. Useful for: - dropdowns - radio/checkbox style choices - lookup results | Field | Type | Description | |---|---|---| | `value` | `Object` | The underlying data value | | `label` | `String` | Display text shown to the user | | `description` | `String` | Optional secondary text | | `image` | `String` | Optional image URL | | `imageStyle` | `String` | Optional CSS style for the image | | `icon` | `String` | Optional icon identifier (e.g. `"vaadin:male"`) shown next to the label in radio/checkbox groups | The `icon` field is populated automatically when `@Icon` is placed on an enum constant. It can also be set manually when building options programmatically. Icons are not displayed in `select` or `combobox` controls. ### `RemoteCoordinates` Represents how a field can resolve remote data. Used in relationship-heavy or distributed scenarios. --- ## Common visual primitives These types are often embedded in pages and forms: - `Text` - `Image` - `Avatar` - `Badge` - `Notification` - `Popover` - `Element` - `MicroFrontend` - `Scroller` - `SplitLayout` - `AccordionLayout` - `TabLayout` - `FullWidth` These are worth knowing because they are the building blocks of richer fluent UI composition. --- ## Status and notifications ### `Status` Maps semantic state to a `StatusType`. ### `NotificationVariant` Defines the visual variant of notifications/messages. ### `Message` Convenient high-level feedback type returned by actions. --- ## Mental model Useful types are the vocabulary around the DSL. They are the pieces that make routing, forms, listings, effects and composition work together. --- # Wire specification & derivation semantics URL: https://mateu.io/reference/wire-specification/ > The versioned contract every Mateu backend emits and every renderer consumes — the envelope, the component model, and the derivation rules that turn a declared model into wire. The single place a re-implementer needs. This is the **authoritative index** for the Mateu wire: the JSON contract a backend produces and a renderer consumes, plus the **derivation semantics** — the rules that turn a declared model into that wire. It exists so a re-implementer (a new renderer, or an alternate producer) can reproduce **the behaviour, not just the shape**. It gathers and points at the normative sources rather than restating them, so there is one contract, not several drifting copies. See also: [Renderer contract](/design-systems/renderer-contract/) (what a renderer must do), [Bring your own design system](/design-systems/bring-your-own-design-system/), and [Portability & exit strategy](/mateu-about/portability-and-exit/). ## Status and versioning - **Current wire version: `3.0`.** Every response envelope carries it as `wireVersion` (see below), so a consumer can guard against a mismatched producer. - **Compatibility policy:** **additive within a major**. New optional fields and new component types may be added without bumping the major; a consumer must **ignore unknown fields and unknown component types** gracefully (render a placeholder, keep going). The major version bumps only on a breaking change to existing wire shape or semantics. - **Every first-party renderer checks it** (web/Vaadin, Redwood, React Native, IntelliJ): the same major is accepted whatever the minor; another major shows the user one plain message — *"This app's server speaks Mateu wire 4.x; this renderer supports 3.x…"* — and rendering goes on (unknown fields and types are still tolerated). A response without `wireVersion` is accepted. - **Freeze-and-pin is the supported migration stance:** if you build against the wire (an alternate renderer, or an extraction), pin the `wireVersion` you targeted; that snapshot is a stable contract. - The published JSON Schemas ([below](#the-machine-readable-schemas)) are the machine-readable half; this page is the normative prose for the parts a schema cannot express (behaviour). ## The exchange One endpoint, same shape on every framework and language: ``` POST /{baseUrl}/mateu/v3/sync/{route} // route in the PATH; "_no_route" when empty Body: { "route": "/...", // "" for the root "actionId": "" | "<methodName>", // "" = the route load "componentState": { ... }, "appState": { ... }, "parameters": { ... }, "consumedRoute": "...", "serverSideType": null, "initiatorComponentId": null } ``` - **This is the canonical endpoint** — the one every first-party renderer sends its requests to, and the one to document and build against. The body decides, not the path, so every server (Java, .NET, Python) also serves the older spelling `POST /{baseUrl}/mateu/v3/components/_/action` the same way (the Redwood shell still bootstraps through it); the Java adapters answer any `POST …/mateu/v3/<operation>/…` other than `sse` so. - The response is a **`UIIncrementDto`** (the envelope). The `v3` in `/mateu/v3/sync/…` is a **route path segment**, not the schema version — the schema version is `wireVersion` in the payload. - The **route load** is dispatched as `actionId: ""` (empty), not `"__load__"` — both are treated as idempotent reads. See the transport notes in [Slow connections](/ux-patterns/slow-connections/). - SSE variants stream partial increments for long tasks; each streamed frame is a `UIIncrementDto`. ## The envelope — `UIIncrementDto` | Field | Meaning | |---|---| | `wireVersion` | Wire protocol version this payload conforms to (e.g. `"3.0"`). Always present. | | `commands` | Client commands to run (`SetWindowTitle`, `navigateTo`, `PushStateToHistory`, `CloseModal`, `DispatchEvent`, `MarkAsClean`/`MarkAsDirty`, …). | | `messages` | Toasts / alerts (may be `undoable`). | | `fragments` | Partial UI updates (`UIFragmentDto`: `targetComponentId`, `action` = `Replace`/`Add`/`ReplaceKeepData`, `component`, `state`, `data`). Overlays (dialog/drawer) arrive as `Add`; a state-only refresh arrives as `ReplaceKeepData`, which keeps the component's existing state and data instead of wiping them. | | `banners` + `appendBanners` | Page banners; append vs replace. | | `appData` / `appState` | App-level data / merged app state. | The three "effects" a producer can return from an action reduce to this envelope: **route** change (a command), **ui-delta** (fragments), **data** (fragment `data`/`appData`), and **commands**. A returned `Step`/`List<Step>` (the flow language) lowers 1:1 to `commands` — it is behaviour, not a view. ## The machine-readable schemas Every schema is **generated from the records and pinned by a test**, and served from the repository (raw files on `master` — the URLs editors and the starters point at): **The wire** — what a server sends and a renderer reads: - [`wire-schema.json`](https://raw.githubusercontent.com/miguelperezcolom/mateu/master/backend/shared/uidl/wire-schema.json) — the response envelope (`UIIncrementDto`) and everything reachable from it: every component metadata type (`type`-discriminated), every trigger, command, message, fragment and option, plus the request body (`RunActionRqDto`). Derived from the `mateu-dtos` records through Jackson's own introspection, so it lists exactly the members that travel. It is **open** (unknown members are allowed — a reader must ignore them) and requires nothing but the `type` discriminator, because a member at its default may be absent (see [Normalisation](#normalisation-what-is-normative-vs-noise)). Its test (`WireSchemaTest`) fails on an added member until the schema is regenerated, and fails on a **removed, renamed or retyped** member *even when regenerating*: that is a breaking change and needs a wire major. - **One discriminator is not a bare name, on purpose**: a page/form KPI (`PageDto.kpis`, `FormDto.kpis`) travels as `"type": "KPIDto"` — the DTO's class name — while every other type is its bare name (`"Form"`, `"App"`, `"Crud"`…). It is not registered under a name of its own, the .NET and Python ports emit the same string, the renderers read it, and it is frozen with the rest of the wire: do not "fix" it to `"KPI"` within a wire major. **The authoring surface** — what an author writes in YAML/JSON: - [`uidl-schema.json`](https://raw.githubusercontent.com/miguelperezcolom/mateu/master/backend/shared/uidl/uidl-schema.json) — the component catalog. - [`routes-schema.json`](https://raw.githubusercontent.com/miguelperezcolom/mateu/master/backend/shared/uidl/routes-schema.json) — the route registry (`routes.yaml`). - [`sources-schema.json`](https://raw.githubusercontent.com/miguelperezcolom/mateu/master/backend/shared/uidl/sources-schema.json) — the REST source catalogue (`sources.yaml`). - [`specs-schema.json`](https://raw.githubusercontent.com/miguelperezcolom/mateu/master/backend/shared/uidl/specs-schema.json) — the unified `specs/ui/**` schema (a `oneOf` of every kind). The authored YAML keys *are* the record components (no sugar the schema does not describe). Wire-plumbing types (`ServerSideComponent`, `ModelViewComponent`, `PageView`) are intentionally excluded from the authoring surface — they appear in the wire schema instead. ## Normalisation (what is normative vs. noise) ### Absent == default A member at its type's **zero value** — `null`, `[]`, `{}`, `false`, `0`, `""` — **may be omitted**, and a reader MUST treat an absent member exactly like that zero value. Producers legitimately differ here (the Java backend sends every member; the .NET and Python ones omit most defaults), and both are conformant. The wire schema therefore requires nothing but the `type` discriminator. **Exception — members whose zero is meaningful.** For these the absent value is a NON-zero default, so a producer MUST send `false`/`0` explicitly, and a reader MUST NOT read an absent one as zero: | Member | Absent means | Zero means | |---|---|---| | `MessageDto.duration` (also `CarouselLayoutDto.duration`) | the renderer's default timeout | a sticky toast (every error message is sent with `0`) | | `MenuOptionDto.visible` | visible | hidden | | `DetailsDto.opened`, `FaqItemDto.open`, `FoldoutPanelInfoDto.open` | open | closed | | `CrudlDto.searchable`, `RecordSwitcherDto.searchable` | a search box | no search box | | `HeroSectionDto.centered`, `ContentLayoutDto.asideSticky` | `true` | `false` | | `AutoSaveTriggerDto.debounceMillis` | 800 ms | no debounce | A new member whose zero is meaningful must be added to this table and to the conformance runners' `MEANINGFUL_ZERO` set in the same change. ### What the conformance corpus compares The [conformance corpus](/design-systems/renderer-contract/) defines the canonical normalisation both producers and the reference apply before comparing: - **Drop** server-invented `id`s (not an action's `id` — that is the name the client sends) and members at their default, **keeping** the members of the table above at `false`/`0`. - **Mask** the error boundary's per-request reference (`Reference: <ref>`). - **Sort** object keys. - **Keep** everything that says *what the screen is*: types, field ids, labels, data types, actions, layout structure — and scalar envelope fields such as `wireVersion`. If two producers normalise to the same tree for the same fixture, they are wire-equivalent. This corpus (`conformance/cases/*`) is the **executable half** of this spec: first loads and second requests (an action's messages and commands, an overlay, a rejected save, an error-boundary answer, a wizard's second step, a CRUD's new/edit/view forms, a search). ## Derivation semantics (behaviour a schema cannot express) These are the rules that turn a *declared model* into the wire. They are normative: a producer that wants to be wire-equivalent must reproduce them. The authoritative write-ups are linked; the key thresholds are inlined so a re-implementer does not have to reverse-engineer them. ### Layout inference — [layout-inference](/ux-patterns/layout-inference/) `@AutoLayout` infers structure from the amount/shape of declared data; explicit annotations always win. - **Field weight units:** textarea/richText/html/markdown/image/uploadableImage = 4; grid = 6; radio/checkbox = 2; array/component = 6; else 1. - **Fold-optionals:** editable form, single unnamed section, no tab/inline/composition/component fields, weight > 16, ≥1 required and ≥4 optional → optionals collapse into a one-panel accordion ("More options"). - **Sections → tabs:** read-only view, ≥5 sections, total weight ≥ 30, no sticky section and no explicit `@Toc` → one tab per section. - **Small enum → radio:** an enum with ≤4 constants renders as radio buttons (`@UseRadioButtons` forces it at any size). - `TabLayout` carries `groupRelationship` (`alternative`/`sequential`/`simultaneous`) and `adaptable` (renderers may degrade tabs to an accordion on narrow viewports without losing disclosure semantics). ### Sizing — hug / fixed / fill A component declares a portable sizing intent (`hug` / `fill` / `fixed:<len>`); a listing infers `fill`. In the responsive grid a track's size **is** the sizing intent: `hug` = `auto`, `fixed` = px, `fill` = `fr`. The renderer applies it to the component's host (a `fill` child takes remaining height and scrolls internally). ### Page type & width — [page-templates](/ux-patterns/page-templates/) - **`pageType`** (`landing`/`collection`/`detail`/`form`/`process`/`dashboard`) is on every page: `@PageTemplate` (or a YAML definition's `pageType:`) wins > archetype family > `MetricCard` field → dashboard > default `form`. A definition-only page that declares `pageType:` is wrapped in a `ServerSide` page carrying it (a bare layout has nowhere to put it); the browser expander of a `specsOnly` bundle stamps it on the root component instead (`pageTypeOf` reads either). - **`pageWidth`** (`fixed`/`fullWidth`/`edgeToEdge`): `@PageWidth` on the view wins > `PageWidthSupplier` > null (renderer infers from type/content). - **`labelsAside`** is inferred per form: aside only when single-column AND ≥6 fields AND all labels ≤20 chars AND all single-line widgets; `@FormLayout(labelsAside=…)` overrides. ### Listings, filters & criteria — [filters-and-listing](/ux-patterns/filters-and-listing/) - **Capability model:** a listing declares inputs (`Searchable`, `Filterable<F>`) and implements interactions (`Navigable`, `Editable`, `Creatable`, `Deletable`); gates `canView/canEdit/canCreate/ canDelete` decide which routes/buttons exist. `gridLayout()` = `auto`(→table)/`table`/`list`/`cards`/ `masterDetail`/`tree`. - **A filter field counts as SET only when its value differs from a freshly-constructed instance** of the filters class (untouched fields keep initializers/defaults). Strings match by case-insensitive containment; other basics by equality; free-text search is **word-based** (every whitespace-separated word must be contained, case-insensitive, any order). - **Range/multi-select conditions** travel as `FilterCriterion(field, operator, values)` (`between`/ `gte`/`lte`/`in`), built from `<field>_from`/`<field>_to` keys and value lists; temporal → `dateRange`, `@RangeFilter` numerics → `numberRange`, enums → `multiSelect` (under AutoCrud's crud-filter semantics). - **Totals & grouping:** `@Aggregate`/`@GroupBy` → `ListingData.aggregates/groups` + `CrudlDto.groupBy`; the group column becomes the implicit primary sort; marker rows are excluded from selection/click/edit. ### State coercion (round-trip) — the JS client integerises whole doubles - **Numeric widening:** any `Number` widens into the target numeric field type on both read and write (a `Double` field's `343.0` arriving as `343` must not reset the field). - **Holder fields are excluded from state:** fields typed `Callable`/`Supplier`/`Runnable`/`Component` are dropped on write and skipped on read (initializers survive) — no `@JsonIgnore` needed. ### Route resolution & parameter precedence — [route-registry](/concepts/routes-and-mounts/) - Routes are **relative to the mount**. Resolution merges authored (`routes.yaml` / code suppliers) over derived (annotations); authored wins and short-circuits. - **Parameter precedence (identical on server and in the browser):** `fixed > client state > path > query > defaults`. Fixed params are **re-applied server-side**, never trusted from the client. ### REST sources — [rest-source-catalogue](/concepts/data-sources/) A surface references a named endpoint by `ref`; the catalogue travels separately (`AppDto.restSources` live, or once in `manifest.json` for a bundle). A source gives **selection, not transformation** (`itemsPath`, `totalPath`, `fields` name→path, `valuePath`/`labelPath`, `resultPath`). `proxy` is read off the **resolved** source, server-side, and is the only channel that injects `${secret.KEY}`. ### Behaviour bus — triggers → actions, events Triggers reference an action by id; an action carries confirm + effects. Components communicate over an abstract pub/sub bus: `UICommand.dispatchEvent` emits, `@SubscribeTo`/`@Emits` subscribe (scopes `DOCUMENT`/`COMPONENT`/`SELF`). This is not the DOM event system — it is a logical bus a renderer must provide. ## Agent operability — the MCP projection The wire is self-describing, so it is not only a *rendering* protocol — it is an **agent-operation** protocol. An MCP (Model Context Protocol) server is "a renderer of agents": same self-describing model, tools instead of pixels. The rules below are **normative** so every host (the `frontend/mcp-server/` sidecar and the native endpoint) produces the *same* projection, exactly like the derivation rules above are shared by every renderer. **The projection** — a `UIIncrementDto` deep-walked into a flat, agent-friendly screen: | Projected | Derived from | |---|---| | `title` | `SetWindowTitle` command → else `Page.pageTitle`/`title` → else the listing's `title`. | | `route`, `serverSideType`, `pageType` | the primary `ServerSide` component node. | | `fields[]` `{id,label,dataType,stereotype,required,readOnly,value,options?}` | every `FormField` metadata node, de-duplicated by `fieldId`, declaration order. `value` from the fragment `state` (else the `ServerSide.initialData`). | | `actions[]` `{id,label,shortcut?,confirmationRequired?}` | `ServerSide.actions[].id`; label enriched from a `Button` whose `actionId` matches. **RBAC is already applied server-side** — an action a token may not run never reaches the wire, so it never appears as a tool. | | `listing?` `{title,searchable,columns,filters,rows?,totalElements?,pageNumber?,pageSize?}` | a `Crud` metadata node (`Crudl` is accepted too); `rows` and the paging numbers from the first fragment `data` entry carrying a `page.content` (the answer of a `search`), without the renderer's `_rowNumber`. | | `messages[]`, `commands[]` | `UIIncrementDto.messages`; and non-`SetWindowTitle` `commands` (e.g. `navigateTo`) surfaced so the agent sees navigation/effects. | **The request mapping** — a tool call becomes a sync request (see [The exchange](#the-exchange)): - `mateu_describe_screen(route)` → load: `actionId: ""`. When the answer is an **app shell** (an `App` component aimed at the route), the host follows it to the content it loads — `homeRoute` / `homeConsumedRoute` / `homeServerSideType`, the request the shell's own content area sends — and again through a CRUD mediator, so the agent is given the screen, not the shell. `mateu_run_action` and `mateu_search` are sent where that screen lives (its route, consumed route and `serverSideType`). - `mateu_list_routes()` → the routes of the root answer's `App` menu (each option's `route`, captioned by its `label`). - `mateu_run_action(route, actionId, componentState)` → the action; `componentState` seeds/overrides fields. - `mateu_search(route, searchText, filters)` → the `search` action; `filters` and the `searchText` travel in the `componentState`, where the listing reads them (as the search box writes them). **Two transport gotchas** (verified against a live backend, both belong to the contract): - `consumedRoute` says how much of the route an app shell has already taken, and `null` and `""` are **different requests**: `null` (the server reads it as `"_empty"`) is a **fresh load** — under an app shell it answers the shell, aimed at the route —, while `""` is a **content load**, answered with the screen itself (what the shell asks next, and what a caller that wants the page, not the chrome, sends — see [Build UIs with AI](/build-uis-with-ai/)). - the server encodes the root/empty route as **`"_empty"`** on the wire; a host normalizes it to `""`. **The authoring tools** (the phase-B half: an agent *writing* a screen rather than operating one) ride two reserved sync actions, so the sidecar and the native endpoint share one implementation per backend and the caller's identity and the route's access rules apply as to any action: - `__validate__` — `parameters._yaml` = a YAML definition; the answer carries the validation report on `appData._validation` (`{valid, kind, errors[], warnings[]}`, each issue `{code, message, path, line?, column?}`) and renders nothing. `mateu_validate_uidl` is this call. **Served only to an MCP tool call, or by an app running with `mateu.mcp.enabled=true` or in dev mode** (`mateu.dev=true`; .NET `MateuOptions.Mcp` / development, Python `mcp=True` / `dev=True`): anywhere else it answers 403, so a production app does not hand anonymous callers a validator over its own catalogues. The sidecar's authoring tools therefore need the backend in one of those modes. - `__preview__` — the same text rendered as the page it describes (layout only, no view model); `mateu_preview_uidl` validates first and projects this answer with the rules above. A text that does not parse now renders the reason (`Invalid YAML — line N (path): …`), not a bare "invalid". It stays open on every app — it is the render target of the chat's and live push's `render-screen` and of the IDE's visual editor — and is safe to be: the 256 KiB cap applies before parsing, every component of the catalogue previews with nothing set (an absent child list is an empty one), and a failure in it, as in every reserved action, answers through the error boundary (the generic message + reference), never a raw 500. The validation rules (scalar typing, root classification, the walk, the message texts, the semantic checks) and the tool/resource surface are normative and live with their corpus in `conformance/mcp/README.md` + `conformance/mcp/authoring.json`, pinned by the four implementations. **Two hosts, one projection.** The **sidecar** (`frontend/mcp-server/`, zero-dependency Node) speaks only this wire, so it operates a Java, .NET or Python backend with no backend change. The **native endpoint** serves the same projection from `MateuService` directly, enforcing RBAC natively. Reference implementation + the tool surface: `frontend/mcp-server/README.md` in the repository. ### Live UI push An MCP caller can also send UI to a UI that is open (the phase-C half). Additive wire, all of it: - `AppDto.agentPush: true` — push is on (`mateu.mcp.enabled` + `mateu.mcp.push.enabled`); only then does the UI open its channel and offer "Connect AI". - Three app-level actions (the app's `serverSideType`, exempt from menu resolution, like `_live-updates`), each with `parameters: {sessionId, secret}`: **`_agent-channel`** (+ `route`, `renderer`) over the SSE endpoint — an open-ended stream, a first increment with the session's status, one increment per message, an empty increment every 20 s, the end after 5 minutes (the UI reconnects); **`_agent-pair`** → `Data{_agentPairing: {code, expiresInSeconds}}`; **`_agent-unpair`** → `Data{_agentPairing: null}`. `sessionId` is the UI's per-tab session id (the web's `X-Session-Id`, which the chat sends as its `sessionId` too); `secret` is random, generated by the UI and kept with the session id. - A new command type **`AgentPush`**, data `{kind, event, detail}`: | kind | event | detail | |---|---|---| | `status` | `mateu-agent-status` | `{paired, agents: [label…]}` — the UI updates its Connect AI control | | `render` | `render-screen` | `{yaml, target: content\|drawer\|dialog, title?}` — applied like the chat's `render-screen` | | `navigate` | `navigation-requested` | `{route, consumedRoute, actionId?, baseUrl?, serverSideType?, uriPrefix?}` | | `event` | the event's name | the event's detail | The events are the chat stream's catalogue ([AI chat → the event catalogue](/ai/#the-event-catalogue)), so a UI applies a pushed message with the code that applies the chat's. Addressing, pairing and limits are normative in `conformance/mcp/README.md` ("Live UI push") and pinned by `conformance/mcp/push.json`; the user-facing guide is [Agent operability → Drive a live UI](/reference/agent-operability/#drive-a-live-ui). ## Conformance A renderer's coverage is measured, not asserted, by the harness in `e2e/conformance.*` against shared fixtures, at three levels — **Core** / **Standard** / **Full**. The producer side is pinned by the wire [conformance corpus](/design-systems/renderer-contract/) (`conformance/cases/*`), run by all three backends (`WireConformanceTest` / `test_wire_conformance.py` / `WireConformanceTests`). Passing the corpus at a wire version **is** the definition of "wire-equivalent at that version". ## What is NOT normative (escape hatches) Deliberately outside the contract, and relegated so they are never the entry cost: `run-js`, an arbitrary custom web-component behind a `custom` field or renderer, and a `ComponentAdapter` that renders a non-Mateu object. A renderer may decline these and still be Core/Standard conformant; they do not travel as portable data the way the declared model does. See [Escaping the framework](/java-user-manual/advanced/escaping-the-framework/). --- # AI URL: https://mateu.io/ai/ > Integrate an AI chat assistant into your Mateu application using the @AI annotation. Mateu lets you embed an AI chat assistant directly into your application shell. Once enabled, a floating **IA** button appears in the navigation bar. Clicking it opens a side panel with a streaming chat interface backed by a Server-Sent Events (SSE) endpoint of your choice. ## Enabling the AI chat :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Add `@AI` to your root UI class and provide the SSE endpoint URL: ```java @UI("") @Title("My App") @AI(sse = "/api/ai/chat") public class MyApp { @Menu Users users; @Menu Reports reports; } ``` That is all that is required on the Java side. ## MCP tools and file uploads `@AI` has two optional attributes beyond `sse`: - `mcp` — path (or absolute URL) of the app's MCP endpoint. The chat forwards it with every message so the agent can operate **this** app through its tools. - `upload` — path (or absolute URL) where the chat POSTs attached files (multipart). When set, the chat panel shows an **attach** button; each upload is saved server-side (its URL travels to the frontend as `ChatDto.uploadUrl`) and the assistant reads it — your endpoint decides where it is stored and how the agent reaches it (e.g. through a filesystem MCP server). Empty (the default) = no file attachments. ```java @UI("") @AI(sse = "/api/ai/chat", mcp = "/api/ai/mcp", upload = "/api/ai/upload") public class MyApp { ... } ``` ## How it works 1. Mateu reads the `sse` value from `@AI` at startup. 2. It propagates the URL through `AppDto.sseUrl` to the frontend. 3. The app shell renders a `mateu-chat` panel in its content row, on the content's start side: on a wide viewport it pushes the page aside (resizable, with a ⤢ wide mode), on a narrow one it covers the content area — never the header. 4. A **chat** toggle (the conversation icon) is added to the shell's header widgets (or the sidebar, depending on the app variant — see below). 5. Clicking it shows or hides the chat panel. 6. The chat panel connects to the SSE endpoint and streams responses back to the user. ## SSE endpoint contract `mateu-chat` sends a **POST** request to the SSE URL with a JSON body and streams back the response as Server-Sent Events. ### Request **Headers** | Header | Description | |-----------------|--------------------------------------------------| | `Authorization` | `Bearer <jwt>` — present when the user is logged in | | `X-Session-Id` | Mateu session identifier | | `Content-Type` | `application/json` | | `Accept` | `text/event-stream` | `Authorization` and `X-Session-Id` go only to an endpoint on an origin trusted with the user's credentials — the app's own backend and the remotes its menu names. A chat endpoint (or upload endpoint) on any other origin is called without them, on every renderer. **Body** ```json { "message": "Show me order ORD-42", "sessionId": "chat-session-nanoid", "menuContext": [ { "path": ["Orders", "List"], "navigation": { "route": "/orders", "consumedRoute": "", "actionId": "", "baseUrl": "/_orders", "serverSideType": "com.example.OrderHome", "uriPrefix": "" } }, { "path": ["Customers"], "navigation": { "route": "/customers", "consumedRoute": "", "actionId": "", "baseUrl": "/_customers", "serverSideType": "com.example.CustomerHome", "uriPrefix": "" } } ] } ``` Every message also carries what the user is LOOKING AT, so the agent grounds its answers and actions on it — if the user is already on the relevant screen, it acts there instead of navigating away. | Field | When | What | |---|---|---| | `message` | always | The user's text input. | | `sessionId` | always | A stable, unguessable per-panel id, useful for conversational memory, uploads or logging. | | `currentRoute` | always | The route of the screen the question is asked from (an agent gateway can route by it). | | `context` | always | A snapshot supplied by the shell: current url and screen title, `appState`, `appData`, and the active component's state and data. | | `screen` | when there is one | A self-describing projection of the current screen — `title`, `fields` (`id`, `label`, `dataType`, `value`) and `actions` (`id`, `label`) — the same shape an [MCP agent](/reference/agent-operability/) gets, so the assistant fills and runs precisely instead of guessing from raw state. | | `mcpUrl` | when `@AI(mcp=…)` is set | The app's MCP endpoint, as an absolute url, so the agent can operate THIS app. | | `attachments` | when files were attached | `[{"name", "path"}]` as returned by the `@AI(upload=…)` endpoint. | | `menuContext` | first message only | The application menu flattened into navigable screens: breadcrumb `path` (e.g. `["Bookings", "List"]`), optional `description`, and the exact `navigation` payload that opens it. Cache it against `sessionId` if you need it later in the conversation. | A relative `sse`, `mcp` or `upload` url is resolved against the app's own backend by every renderer (the browser against the page's origin; the native renderers against the backend they are connected to). ### Response The response is a stream of Server-Sent Events, read as SSE: an event ends at a blank line, its `data:` lines are joined with a newline, only the single optional space after `data:` is dropped (indentation survives), and comment lines (`: keep-alive`) are ignored. Plain-text events are **line-oriented**: each one is **one line of the reply**, and the lines are joined with newlines, so markdown structure (headings, lists, code fences, tables) survives. To stream token by token, use `agent-delta` events instead (below). Each event's data is interpreted, in order of precedence, as: 1. **Token usage** — a JSON object with any of `inputTokens`, `outputTokens`, `totalTokens`. It is not shown as text; the values are merged into the token bar under the message list: ``` data: {"inputTokens": 1200, "outputTokens": 340, "totalTokens": 1540} ``` 2. **UI event** — a JSON object with a string `event` field (`detail` is optional and defaults to `{}`). It is consumed silently and dispatched as a DOM `CustomEvent` — except the reserved `agent-error` event, whose `detail.message` is rendered as a warning in the reply bubble instead: ``` data: {"event": "navigation-requested", "detail": { ... }} data: {"event": "agent-error", "detail": {"message": "The agent timed out."}} ``` 3. **Text** — anything else is one line of the agent's markdown reply, appended to the current bubble. After `agent-delta` events, the next text event is instead the **whole, final reply** and replaces what was streamed (so the server can send the answer cleaned up — without markers, after a guardrail — once it is complete). #### Streaming and progress (optional) An agent that wants the user to see the answer as it is written, and what it is doing until then, sends these reserved events. All are optional, and a client that predates them just dispatches them as DOM events and ignores them. | Event | `detail` | What the chat does | |---|---|---| | `agent-delta` | `{"text": "…"}` | Appends a piece of the reply (any size, newlines included — it is JSON, so a piece is never cut at a line). | | `agent-status` | `{"phase": "resolving \| guardrails \| connecting \| thinking", "text": "…"}` | Shows `text` in the progress line under the conversation, with the seconds spent in that phase. | | `agent-tool` | `{"name", "server", "kind", "phase": "start \| end", "ms", "error"}` | While a tool runs, the progress line reads «Llamando a `name`… N s»; the turn's tool calls are listed under the reply, with their duration or error. | ``` data: {"event":"agent-status","detail":{"phase":"thinking","text":"Pensando…"}} data: {"event":"agent-tool","detail":{"name":"booking_findBookings","server":"booking","kind":"mcp","phase":"start"}} data: {"event":"agent-tool","detail":{"name":"booking_findBookings","server":"booking","kind":"mcp","phase":"end","ms":1510}} data: {"event":"agent-delta","detail":{"text":"Tienes 3 "}} data: {"event":"agent-delta","detail":{"text":"reservas."}} data: {"inputTokens":250,"outputTokens":30,"totalTokens":280} data: Tienes 3 reservas. ``` Usage objects whose counters are all zero are ignored (older agents sent them as placeholders while working). The token bar shows the last usage received; it is not summed across replies. There is no end-of-stream sentinel (no `[DONE]`): the reply is finished when the server closes the stream. If the stream closes without any text, the chat shows a warning suggesting the LLM is not configured. Mateu also forwards the current JWT and session-id as request headers so your endpoint can authenticate and personalise responses. ### Message rendering: markdown, images, and inline SVG Agent replies render as **markdown** (via `mateu-markdown`: marked + DOMPurify). Sanitization uses the **html + svg** profiles, so replies may safely embed: - **Images**, including `data:` URIs — e.g. a chart generated server-side and inlined as `![sales](data:image/png;base64,...)`. - **Inline `<svg>`** — e.g. a diagram of the user's model rendered by a tool and pasted straight into the reply. The chat bubble sizes both to its width (`max-width: 100%`, height auto), so diagrams and images fit the panel without horizontal scrolling. Custom elements also pass sanitization, so a reply can even instantiate web components available in the host page. ## Supported app variants The chat panel is drawn by every navigating shell variant of the web renderer; where its toggle sits depends on the variant: | Variant | Chat toggle | |---|---| | `MENU_ON_TOP`, `HAMBURGER_MENU`, `HAMBURGER_SECTIONS`, `TILES`, `TABS` | In the header's widget zone (end side), before the app's own widgets | | `MENU_ON_LEFT` | At the bottom of the left sidebar | | `RAIL`, and a `chromeless` app | No toggle: open it from the [command center](/ux-patterns/command-center/)'s "Ask AI" row | The embedded `MEDIATOR` shell (a CRUD nested in a page) draws no chat of its own. ## Example: Spring AI SSE endpoint ```java record ChatRequest( String message, String sessionId, String currentRoute, Map<String, Object> context, Map<String, Object> screen, // may be null String mcpUrl, // may be null List<Attachment> attachments, // may be null List<MenuContextEntry> menuContext // first message only ) {} record Attachment(String name, String path) {} record MenuContextEntry(List<String> path, Map<String, Object> navigation) {} @RestController @RequestMapping("/api/ai") public class AiChatController { private final ChatClient chatClient; public AiChatController(ChatClient chatClient) { this.chatClient = chatClient; } @PostMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chat(@RequestBody ChatRequest req) { // Build a system prompt that describes the available screens // menuContext only travels with the first message of a session String menuDescription = Optional.ofNullable(req.menuContext()).orElse(List.of()).stream() .map(e -> "- " + String.join(" > ", e.path()) + " → " + e.navigation()) .collect(Collectors.joining("\n")); String systemPrompt = """ You are an assistant for this application. The following screens are available (path → navigation payload): %s When the user asks to open a screen, emit a navigation event at the END of your response: data: {"event": "navigation-requested", "detail": <navigation payload>} Only emit one event. Never show the raw JSON to the user. """.formatted(menuDescription); // The contract is line-oriented: each SSE data event must be ONE line // of the reply, so buffer the token stream and emit complete lines. return chatClient.prompt() .system(systemPrompt) .user(req.message()) .stream() .content() .bufferUntil(token -> token.contains("\n")) .map(tokens -> String.join("", tokens).stripTrailing()); } } ``` ## LLM-driven UI interactions The AI assistant is not limited to returning text. It can also **trigger UI actions** — navigation, form updates, or any custom behaviour — by emitting a special JSON event inside the SSE stream. ### Event format Any `data:` line whose payload is a JSON object with an `event` field is treated as a UI event instead of chat text: ``` data: {"event": "<event-name>", "detail": { ... }} ``` `mateu-chat` will: 1. Parse the JSON. 2. Dispatch `new CustomEvent(event, { detail, bubbles: true, composed: true })`. 3. **Not** display the JSON in the chat message — it is consumed silently. Text tokens and UI events can be freely mixed in the same stream. ### Built-in event: `navigation-requested` Mateu's app shell listens for `navigation-requested` and routes the user to the specified view. Payload fields: | Field | Type | Description | |------------------|--------|--------------------------------------------------| | `route` | string | Target route (e.g. `/orders/123`) | | `consumedRoute` | string | Route consumed by the app shell (usually `""`) | | `actionId` | string | Action to trigger on arrival (e.g. `"view"`) | | `baseUrl` | string | Base URL of the target micro-frontend | | `serverSideType` | string | Fully-qualified Java class of the target UI | | `uriPrefix` | string | URI prefix (usually `""`) | Example — navigate to a specific order: ``` data: {"event": "navigation-requested", "detail": {"route": "/orders/ORD-42", "consumedRoute": "", "actionId": "view", "baseUrl": "/_orders", "serverSideType": "com.example.OrderHome", "uriPrefix": ""}} ``` ### Built-in event: `close-requested` Closes the chat panel (no `detail`). A `Chat` component placed on a page has nothing to close into, so it shows no close button and ignores the event. ### Built-in event: `render-screen` The agent can author a screen and have it shown. `detail`: | Field | Type | Description | |---|---|---| | `yaml` | string | The screen, as a YAML definition (the same component catalogue as `specs/ui/**`; `uidl-schema.json` describes it). | | `uidl` | object or string | The same, as a JSON component tree — an alternative to `yaml` (`yaml` wins when both are sent). | | `target` | string | `content` (default), `drawer` or `dialog`. | | `title` | string | The drawer's or dialog's header. | ``` data: {"event": "render-screen", "detail": {"yaml": "type: VerticalLayout\ncontent:\n - type: Text\n text: Check-in for Nora Duarte\n", "target": "drawer", "title": "Check-in"}} ``` It is handled the moment it arrives — the reply can go on streaming under it — in one of two ways: 1. **A page subscribes to it.** A view on screen annotated `@SubscribeTo(event = "render-screen", action = "…")` takes it: its action runs with the `detail` as parameters (read `yaml` from `httpRequest.runActionRq().parameters()`), and it renders the screen however it likes — inside its own layout, next to other content. 2. **Nobody subscribes: the shell renders it.** The built-in render target posts the definition to the backend's reserved `__preview__` action (the one the visual editor uses), which turns it into a normal UI increment through the real mapper, and shows it in the content area, or in a drawer or a dialog over the current page. In the content area it is transient: any navigation — the same menu entry included — brings the route's own screen back; and, like a navigation, it first asks before discarding unsaved changes of the screen it replaces (a drawer or dialog replaces nothing). An invalid definition shows the preview's own "Invalid or empty YAML" notice. A static bundle has no backend: there, a `uidl` (JSON) screen is expanded in the browser and a YAML one shows why it cannot be. `__preview__` renders only what it is given: no view model is created or bound, so it shows the user nothing of the application they could not already see. It still goes through the route guard (a route whose `access:` refuses the caller answers 403) and the wire-type policy, and the wire-only component types (a `ServerSideComponent` naming a class) are not authorable, so a definition cannot smuggle in an island bound to a view model. Whatever the rendered screen does afterwards — its buttons, its REST sources — goes through the same checks as any other request. **An agent's screen is untrusted, and runs no code.** An LLM can be steered by the data it reads (prompt injection), so pairing an agent grants "drive my UI" — navigate, fill, click, which the user could do anyway — never "run code in my signed-in tab". Every shell renders an agent's screen (`render-screen` from the chat or from a live push) through `__preview__` with `_untrusted: true`, and the backend — Java, .NET and Python alike — takes out of it everything that could run script: - an `Element` keeps no event-handler attribute (`on…`), no `srcdoc`, no `import` module and no unsafe URL attribute (only relative, `http(s):`, `mailto:` and `tel:` links); its content is shown as text (`html: false`); an element that loads or runs code (`script`, `iframe`, `object`, `embed`, `style`, `base`, `link`, `meta`, `template`, …) or a framework element (`mateu-*`) becomes an empty `div`. Its `on:` events still run the screen's own actions, like a button; - `RunJS` rules, an action's `js` and `AddContentToHead` / `AddContentToBody` commands are dropped; - a `javascript:` / `vbscript:` URL anywhere is blanked; - a `MicroFrontend` does not load from another server (an absolute `baseUrl` is dropped). Everything else renders as authored. The web renderers (Vaadin and Redwood) apply the same rules again in the browser — a static bundle expands a JSON screen locally, and an older backend ignores the flag. The rules are pinned by one set of cases, `conformance/untrusted/cases.json`, run by every implementation. The visual editor's preview — your own YAML — does not send the flag and renders as written. ### The event catalogue Every renderer reads the stream the same way and handles the same events: | Event | Vaadin (web) | Redwood (VB) | React Native | IntelliJ | |---|---|---|---|---| | text / `agent-delta` | Markdown answer, streamed | Markdown answer, streamed | Markdown answer, streamed | Markdown answer, streamed | | `agent-status` / `agent-tool` | Progress line + the turn's tool steps | Progress line + tool steps | Progress line | Progress line | | usage | Token bar (last usage) | Token bar | Token line | Token line | | `agent-error` | Warning in the reply | Warning in the reply | Warning in the reply | Warning in the reply | | `navigation-requested` | Like a menu click with all the fields; outside an app shell, route resolution | Like a menu click with all the fields (`baseUrl`/`uriPrefix` register a remote) | Like a menu click (route, consumedRoute, serverSideType, baseUrl — another backend gets its own session, which carries the user's credentials only when the app's menu names that backend; an `actionId` with no route runs as an app action) | Like a menu click (one backend per session, so `baseUrl`/`uriPrefix` are not used) | | `close-requested` | Closes the panel (ignored by a `Chat` on a page) | Closes the panel | Closes the panel | Closes the dialog / hides the inline panel | | `render-screen` | Subscriber first, else content / drawer / dialog | Subscriber first, else content / drawer / dialog | Subscriber first, else content / sheet | Subscriber first, else a transient Preview tab / side window / dialog | | anything else — only an event a view on screen subscribes to | A DOM `CustomEvent` (bubbling, composed) for the `@SubscribeTo` views — page scripts hear it too | A DOM `CustomEvent` + the `@SubscribeTo` views on screen | The session event bus (`@SubscribeTo` views) | The session event bus (`@SubscribeTo` views) | An agent cannot fire just any event at the app. Besides the three built-in ones, an event goes out only while a view on screen declares it (`@SubscribeTo(event = …)`), and never when it is one of the framework's own event names (`server-side-action-requested`, `route-changed`, `page-banners-received`, `dirty`, `mateu-…`, DOM events…) — whatever a view declares. Anything else is dropped. The lists are pinned by `conformance/client/agent-events.json`. Links in an answer to a screen of the app (`[Nora Duarte](/booking/bookings/4MBZS7)`) open it in the app through the menu entry that serves it, on every renderer. Attachments are offered wherever an upload endpoint is declared (React Native: images, through the photo picker). The same events can also come from **outside the chat**: an MCP agent paired with the tab sends them through the app's live UI push channel (`mateu_push_ui`, `mateu_navigate`, `mateu_dispatch_event`), and every renderer applies them with the code above. See [Agent operability → Drive a live UI](/reference/agent-operability/#drive-a-live-ui). ### Custom events You can define your own events and handle them anywhere in your component tree. Backend — emit the event mid-stream: ```java // Inside your SSE Flux, emit this frame after the answer tokens: String frame = "data: " + objectMapper.writeValueAsString(Map.of( "event", "highlight-row", "detail", Map.of("id", orderId) )) + "\n\n"; ``` Frontend — listen for it in a custom web component or page: ```js document.addEventListener('highlight-row', (e) => { highlightRow(e.detail.id); }); ``` ### System prompt guidance To make the LLM emit these events reliably, describe the contract in the system prompt: ``` You are an assistant for the Orders application. When the user asks to open or view a specific record, emit a navigation event at the END of your response, after any explanatory text: data: {"event": "navigation-requested", "detail": {"route": "/orders/<id>", "consumedRoute": "", "actionId": "view", "baseUrl": "/_orders", "serverSideType": "com.example.OrderHome", "uriPrefix": ""}} Only emit one event per response. Never show the raw JSON to the user. ``` ## Summary - Annotate your root UI class with `@AI(sse = "<url>")`. - Implement an SSE endpoint at that URL (Mateu ships the chat panel and its contract, not the agent). - Mateu handles the rest: button, panel, streaming UI. - Stream the reply line by line, or token by token with `agent-delta` events (and `agent-status` / `agent-tool` to show progress); replies render as markdown and may embed images (`data:` URIs included) and inline SVG. - Emit `{"event": "...", "detail": {...}}` in the stream to trigger UI actions from the LLM; emit token-usage JSON to feed the token bar. **Related:** the [command center](/ux-patterns/command-center/) (`@App(commandCenter=true)`) adds an always-present palette that unifies navigation, global search and an AI hand-off — an AI-adjacent entry point alongside the IA button. --- # Use Mateu with AI assistants URL: https://mateu.io/ai-assistant-reference/ > Context files for Claude, Gemini, Cursor, and other AI tools to generate correct Mateu code. AI coding assistants generate much better Mateu code when they have the API in their context. This page provides ready-to-use reference files for the most common tools. ## Projects ship their own guidance A project created from the [New Project front doors](/java-create-your-project/) (IntelliJ, VS Code, the Maven archetype) — and every [starter](https://github.com/miguelperezcolom/mateu/tree/master/starters) — carries an **`AGENTS.md`**: what the project is, its layout, how to run it, where its UI is declared and the rules an assistant must respect. Its **`CLAUDE.md`** imports it (`@AGENTS.md`), so Claude Code reads the same text as Codex, Cursor, Copilot and the other tools that read `AGENTS.md`. Each flavour gets its own: a YAML-only project's assistant is told to edit `specs/ui` and not to add Java UI classes. ## Reference files | File | Size | Best for | |---|---|---| | [Compact reference](https://mateu.io/mateu-ai-compact.md) | ~2 500 tokens | Day-to-day code generation, tools with small context windows | | [Full reference](https://mateu.io/mateu-ai-full.md) | ~9 000 tokens | Thorough assistance, broad feature coverage, Gemini 1.5 / Claude Projects | | [llms-full.txt](https://mateu.io/llms-full.txt) | the whole site | Tools that ingest a documentation site in one file (generated from these pages at build time) | Both files are plain Markdown — paste them directly, link to them, or download them. --- ## How to use with each tool ### Claude Code / Claude Agent SDK Install the **`mateu` plugin** from the marketplace in the Mateu repository — a family of **skills** that activate as soon as you ask for Mateu work (*"create a CRUD for…"*, *"a YAML listing over our REST API"*, *"start a new Mateu app"*, *"run and screenshot this screen"*) and load their references on demand (progressive disclosure), so they cost almost nothing until needed: ```text /plugin marketplace add miguelperezcolom/mateu /plugin install mateu@mateu ``` Projects made by the New Project generators already enable it in `.claude/settings.json`. Skills: `mateu` (Java), `mateu-screen`, `mateu-yaml` (YAML specs and static bundles), `mateu-dotnet`, `mateu-python`, `mateu-scaffold`, `mateu-run`, `mateu-federation` — what each does, and the rest of the AI tooling (AGENTS.md, llms.txt, the JSON Schemas, MCP), is in [Build UIs with AI](/build-uis-with-ai/). With the Claude Agent SDK, load the same skills from [`ai/claude-plugin/mateu/skills`](https://github.com/miguelperezcolom/mateu/tree/master/ai/claude-plugin/mateu/skills) (the plugin directory is the single source; inside the Mateu repository `.claude/skills/` links to it). ### Claude Projects (claude.ai) 1. Open [claude.ai](https://claude.ai) and create or open a **Project**. 2. In the project's **Instructions** section, paste the compact or full reference. 3. Every conversation in that project will have Mateu context automatically. ### Gemini Gems (gemini.google.com) 1. Open [Gemini](https://gemini.google.com) and click **Explore Gems → New gem**. 2. Paste the reference file content in the **Instructions** field. 3. Save the Gem as "Mateu developer". Use it for every Mateu coding session. Gemini 1.5 Pro and 2.0 Flash both have large enough context windows for the full reference. ### ChatGPT / Custom GPT 1. Go to [chatgpt.com](https://chatgpt.com), open **Explore GPTs → Create a GPT**. 2. In the **Configure** tab, paste the reference in the **Instructions** field. 3. Or, in any regular conversation, paste the compact reference at the start and then ask your question. ### Cursor (cursor.sh) Add a `.cursor/rules` file (or `.cursorrules` at the project root) with the compact reference content. Cursor will include it as context in every AI request for that project. ``` # In .cursor/rules or .cursorrules [paste the contents of mateu-ai-compact.md here] ``` ### GitHub Copilot Copilot reads `/.github/copilot-instructions.md` for project-level context. Copy the compact reference there: ```bash mkdir -p .github curl -o .github/copilot-instructions.md https://mateu.io/mateu-ai-compact.md ``` ### Any other tool Paste the compact reference at the start of your conversation before your first question. Most models will retain it for the session. --- ## What to ask Once the context is loaded, you can ask directly: ``` Create a CRUD for a Product entity with id, name, price, and active fields. ``` ``` Add a wizard with 3 steps: account details, plan selection, and a success screen. ``` ``` Build a dense multi-zone check-in form with @Compact and @Zones. ``` ``` Add a @Banner that warns when the service is in maintenance mode. ``` ``` Create a custom listing for orders with a status filter and server-side pagination. ``` --- ## llms.txt Mateu publishes an [`llms.txt`](https://mateu.io/llms.txt) at the site root following the [llms.txt proposal](https://llmstxt.org/). AI crawlers and tools that support the standard can discover the reference files automatically from there. --- # The authoring rule URL: https://mateu.io/authoring-rule/ > When something is an annotation, an interface, or something Mateu infers for you — and the criterion that decides. Mateu has a large declarative surface. It has stayed learnable because of one rule that has governed it from the start — and this page writes it down, because a rule nobody can read is a rule only the maintainer can apply. If you are extending Mateu, this decides where your new capability belongs. If you are only using it, it explains why the API looks the way it does, and lets you guess right about parts you have not read yet. ## Two questions The first splits by **when the answer is known**: > **Annotation** — purely declarative: known at compile time, no decision to make. > **Interface (supplier / abstract method)** — there is a decision, and it is taken at runtime. That is why a page's subtitle is `@Subtitle("…")` *and* `SubtitleSupplier.subtitle()`: one is a constant, the other is computed. The same pair appears for the title, the overline, the title placeholder, peer navigation, page width. **When both are present, the supplier wins** — a runtime value outranks a declared one. The second question splits by **who decides**: | | **you decide** | **Mateu decides** | |---|---|---| | **compile time** | annotation | inference from the shape of your model | | **runtime** | interface / abstract method | inference + composition | The left-hand column is the rule above. The right-hand column is [layout inference](/ux-patterns/layout-inference/) and page inference: Mateu reading the information you declared and choosing the presentation you did not. This is why `@AutoPage` feels unlike every other annotation: **its content is not information, it is permission** — "decide this for me". It is not a declaration, it is a change of column. ## The criterion From those two axes comes the rule that decides where a new capability goes: > **An annotation is legitimate when it carries information that only you have.** > **It is debt when it carries a decision Mateu could take by looking at the model.** A `@Timestamp` field marks *which* of your fields is the last-updated one — Mateu cannot know that; information only you have. A two-column layout for a form of six short fields is *not* information: it is a decision derivable from the fields, so it is inferred, and the annotation exists only to override. Applied consistently, the surface shrinks as inference improves instead of accumulating. ## It also decides where your screen runs The same partition governs delivery, which is why it is worth getting right: | Authoring | Delivery | |---|---| | **annotation** — compile time, no decision | can be pre-rendered into a [static bundle](/deploy/static-bundle/) and served from a CDN | | **interface** — decision at runtime | needs the server | Both ask the same thing: *can this be known without the request?* So the rule of thumb for "will this screen work with no backend" is not a list of exceptions to memorise — it is **if you declared it with annotations, it can ship statically; if you used an interface, it needs a server.** ## The surface is measured The rule above decides case by case. The risk it cannot catch is **accumulation**: every annotation is justifiable on its own, and the sum still drifts the framework away from the reason it exists. So it is counted. `scripts/annotation-density.py` measures how many Mateu annotations a screen needs across the demo and e2e corpus — **4.38 per screen over 444 screens** as of 2026-08-12 — and CI fails if the average creeps above a recorded ceiling. The ceiling carries deliberate headroom (~5%): pinned to the exact current value it would fail on the very next annotation added anywhere, and a check that fires on ordinary work gets raised by reflex until it means nothing. Raising it is allowed. Raising it *silently* is the thing the number exists to prevent. ## What Mateu will not infer Inference has a ceiling, and it is worth knowing where it is so you do not wait for a version that lifts it. See [the limits of inference](/ux-patterns/layout-inference/#the-limits-of-inference). --- # Build a full backoffice in 10 minutes URL: https://mateu.io/build-a-full-backoffice-in-10-minutes/ This is the fastest way to understand what Mateu is really for. In a few minutes, you can go from a Spring Boot project to a working backoffice with: - forms - validation - actions - navigation - relationships - browser feedback And you do it all in Java. --- ## What you'll build A small admin app with: - a home screen - a menu - a CRUD screen - validation - a foreign key relationship - a success notification No frontend project. No REST controllers for each screen. No duplicated models. --- ## Step 1 — Create the UI root :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Start with a screen: ```java @UI("/admin") @Title("Admin") public class AdminHome { @Menu AdminMenu admin; } ``` ```java public class AdminMenu { @Menu RolesCrud roles; } ``` This already gives you: - a UI root - a navigation entry - a place to expose your backoffice modules --- ## Step 2 — Create a real form Now define the form for one entity. ```java public class RoleViewModel implements Identifiable { @EditableOnlyWhenCreating @NotEmpty String id; @NotEmpty String name; @Colspan(2) @Style("width: 100%;") String description; @Lookup(search = PermissionIdOptionsSupplier.class, label = PermissionIdLabelSupplier.class) @Colspan(2) @Style("width: 100%;") @Stereotype(FieldStereotype.checkbox) List<String> permissions; @Override public String id() { return id; } public String create(HttpRequest httpRequest) { return id; } public void save(HttpRequest httpRequest) { } } ``` In one class, you just defined: - state - validation - layout hints - rendering intent - a relationship - create/save lifecycle --- ## Step 3 — Connect it to your application layer Now wire the form to your actual use cases. ```java public class RoleViewModel implements Identifiable { @EditableOnlyWhenCreating @NotEmpty String id; @NotEmpty String name; @Colspan(2) @Style("width: 100%;") String description; @Lookup(search = PermissionIdOptionsSupplier.class, label = PermissionIdLabelSupplier.class) @Colspan(2) @Style("width: 100%;") @Stereotype(FieldStereotype.checkbox) List<String> permissions; final CreateRoleUseCase createRoleUseCase; final SaveRoleUseCase saveRoleUseCase; public RoleViewModel(CreateRoleUseCase createRoleUseCase, SaveRoleUseCase saveRoleUseCase) { this.createRoleUseCase = createRoleUseCase; this.saveRoleUseCase = saveRoleUseCase; } public String create(HttpRequest httpRequest) { createRoleUseCase.handle(new CreateRoleCommand(id, name, description, permissions)); return id; } public void save(HttpRequest httpRequest) { saveRoleUseCase.handle(new SaveRoleCommand(id, name, description, permissions)); } @Override public String id() { return id; } } ``` Mateu does not replace your application architecture. It sits on top of it. --- ## Step 4 — Expose the CRUD Now expose the form through a `Crud`. The whole lifecycle — listing, view, edit, create, delete, persistence — lives on the orchestrator, wired straight to your query services and use cases. ```java @Title("Roles") public class RolesCrud extends Crud< RoleViewModel, RoleViewModel, RoleViewModel, NoFilters, RoleRow, String> { final RoleViewModel viewModel; final RoleQueryService queryService; final DeleteRoleUseCase deleteRoleUseCase; public RolesCrud( RoleViewModel viewModel, RoleQueryService queryService, DeleteRoleUseCase deleteRoleUseCase) { this.viewModel = viewModel; this.queryService = queryService; this.deleteRoleUseCase = deleteRoleUseCase; } @Override public ListingData<RoleRow> search(SearchRequest request, HttpRequest httpRequest) { return queryService.findAll(request.searchText(), filters(request), request.pageable()); } @Override public RoleViewModel view(String id, HttpRequest httpRequest) { return viewModel.load(queryService.getById(id).orElseThrow()); } @Override public RoleViewModel edit(String id, HttpRequest httpRequest) { return viewModel.load(queryService.getById(id).orElseThrow()); } @Override public RoleViewModel creationForm(HttpRequest httpRequest) { return viewModel; } @Override public void deleteAllById(List<String> selectedIds, HttpRequest httpRequest) { deleteRoleUseCase.handle(new DeleteRoleCommand(selectedIds)); } @Override public String save(HttpRequest httpRequest) { var form = httpRequest.getComponentState(RoleViewModel.class); form.save(httpRequest); return form.id(); } @Override public String create(HttpRequest httpRequest) { var form = httpRequest.getComponentState(RoleViewModel.class); return form.create(httpRequest); } } ``` Now you have a real CRUD screen in your backoffice. --- ## Step 5 — Resolve relationships dynamically Mateu can resolve foreign keys dynamically through backend suppliers. ### Options supplier ```java public class PermissionIdOptionsSupplier implements LookupOptionsSupplier { final PermissionQueryService queryService; public PermissionIdOptionsSupplier(PermissionQueryService queryService) { this.queryService = queryService; } @Override public ListingData<Option> search(String fieldName, String searchText, Pageable pageable, HttpRequest httpRequest) { var found = queryService.findAll(searchText, null, pageable); return new ListingData<>(new Page<>( searchText, found.page().pageSize(), found.page().pageNumber(), found.page().totalElements(), found.page().content().stream() .map(permission -> new Option(permission.id(), permission.name())) .toList() )); } } ``` ### Label supplier ```java public class PermissionIdLabelSupplier implements LookupLabelSupplier { final PermissionQueryService queryService; public PermissionIdLabelSupplier(PermissionQueryService queryService) { this.queryService = queryService; } @Override public String label(String fieldName, Object id, HttpRequest httpRequest) { return queryService.getLabel((String) id); } } ``` So your form can work with real relationships without moving logic into the frontend. --- ## Step 6 — Return user feedback directly You can return browser feedback straight from backend methods. ```java @Button public Message notifySave() { return new Message("Role saved successfully"); } ``` Mateu turns that into a browser notification. No frontend toast code required. --- ## What you just built With a small amount of Java, you defined: - navigation - CRUD lifecycle - validation - relationships - rendering behavior - user feedback Mateu handled: - rendering - browser validation - interaction - state binding - UI updates --- ## Why this matters In a traditional stack, this usually means: - backend model - frontend model - API glue - duplicated validation - duplicated relationships - duplicated navigation With Mateu, it stays in one place. --- ## Where to go next If you want the step-by-step version, continue with: - [Your first Mateu app with Spring Boot →](/java-user-manual/start-here/first-app/) - [Build a real CRUD with relationships →](/java-user-manual/build/orders-customers-order-lines/) - [Compose a shell with multiple services →](/java-user-manual/use-cases/distributed-backoffice/) --- ## One sentence summary **This is what Mateu is for: building real backoffice applications with minimal code and without a frontend layer.** --- # Case study: Mateu in a microservices system URL: https://mateu.io/case-study-microservices/ ## The problem In a typical microservices architecture, teams often end up with: - a separate frontend application - duplicated models between frontend and backend - custom APIs for every screen - complex synchronization between layers This leads to slower development and higher maintenance costs. --- ## The approach In this project, Mateu is used to define UI directly inside backend services. Each service: - owns its domain logic - exposes its own UI routes - defines its own screens using Mateu :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Example: ```java @UI("/_users") @Title("Users") public class UsersHome { @Menu UsersMenu users; } ``` Each service defines its own menus and CRUD flows: ```java public class UsersMenu { @Menu UsersCrud users; @Menu RolesCrud roles; @Menu PermissionsCrud permissions; } ``` --- ## Architecture - backend services communicate via gRPC - each service exposes UI through Mateu - frontend acts as a renderer, not as an application layer - UI is composed from multiple services --- ## What changed Instead of: - backend + frontend + API You now have: - backend + UI definition (in the same place) --- ## Benefits ### Less duplication No need to redefine models in multiple layers. ### Clear ownership Each service owns: - data - logic - UI ### Simpler architecture No need for: - custom APIs per screen - frontend state synchronization ### Better fit for microservices UI aligns with service boundaries. --- ## When this works best - internal tools - CRUD-heavy systems - enterprise apps - distributed architectures --- ## Summary Mateu allows you to keep UI definition close to the backend that owns the behavior. This reduces complexity and makes microservice-based systems easier to build and evolve. --- 👉 Try the demo: https://vaadin.mateu.io/fluent/use-cases/rra --- # Renderers URL: https://mateu.io/design-systems/ > Where a Mateu UI renders — Vaadin and Oracle Redwood / Visual Builder on the web, the Mateu mobile app, IntelliJ on the desktop — all from the same model. A Mateu UI is a model; a **renderer** turns it into something people use. Every renderer consumes the same wire model, so the same UI — whether it was written in YAML, Java, C# or Python, and whether a backend or a static bundle serves it — renders in any of them without changes. | Renderer | Where | How you choose it | |---|---|---| | [Vaadin](/design-systems/vaadin/) | web browser (the default) | `renderer: vaadin` in `project.yaml`, or the `mateu-vaadin` dependency | | [Oracle Redwood / Visual Builder](/design-systems/oracle-redwood/) | web browser, standalone or **embedded in an existing Visual Builder app** | `renderer: redwood`, or the `mateu-redwood` dependency | | [The Mateu mobile app](/native/react-native/) | iOS and Android | install the app and add the UI's address | | [IntelliJ](/native/) | desktop, inside IntelliJ IDEA | the Mateu plugin, pointed at the UI | For the web renderers, the project's choice lives in [`project.yaml`](/define/yaml/project-settings/); a static bundle ships that renderer, and a served app uses the renderer dependency on its classpath. ## Web or native? Each renderer family serves a different goal. The same UI can be rendered by all of them at once, so you pick per deployment — or offer several. - **Web renderers** (with multiple design systems) — best when you want a **zero-install** UI delivered through the browser, and when you need to **drop Mateu into an application you already have without breaking its UX**. Choose the design system that matches the host application — [Vaadin](/design-systems/vaadin/) or [Oracle Redwood](/design-systems/oracle-redwood/) — and the Mateu screens blend in seamlessly. - **Native renderers** — best when you want **better performance** and an OS-native feel. The [desktop (IntelliJ plugin)](/native/) renderer runs your app inside IntelliJ IDEA and gives power users the IDE's productivity workspace — **docking, split editor tabs, Search Everywhere, keyboard-first navigation**. The [mobile (React Native)](/native/) renderer ships your app to iOS and Android. You don't have to pick just one: the same UI can be used from a browser, from IntelliJ and from a phone at the same time. ## Web renderer artifacts | Renderer | Design system | Dependency | |---|---|---| | [Vaadin](/design-systems/vaadin/) | Vaadin Lumo | `mateu-vaadin` | | [Oracle Redwood](/design-systems/oracle-redwood/) | Oracle Redwood, on Visual Builder | `mateu-redwood` | ## Writing your own The supported renderers are Vaadin and the Redwood/VB line — and that list is short for a reason: four first-party renderers were built and retired, because one renderer per design system, maintained in first person, does not survive a single maintainer. So the useful question is not "which of ours matches your design system" but **"how cheaply can you own yours"**. See the [renderer contract](/design-systems/renderer-contract/): what a renderer has to implement, and the three conformance levels that tell you when you are done. Reaching **Core** is a complete, legitimate answer. ## How to switch renderer Replace the renderer dependency in your `pom.xml`. For example, to switch from Vaadin to Redwood: ```xml  <dependency> <groupId>io.mateu</groupId> <artifactId>mateu-vaadin</artifactId> <version>3.0-beta.7</version> </dependency>  <dependency> <groupId>io.mateu</groupId> <artifactId>mateu-redwood</artifactId> <version>3.0-beta.7</version> </dependency> ``` Nothing in the UI definition changes. A YAML-only project switches with `renderer:` in `project.yaml`. ## Embedding in existing UIs Because each renderer is a web component, you can embed a Mateu UI inside any existing application — including React, Vue, Angular, or plain HTML pages — regardless of which design system that application uses. A Vaadin-rendered Mateu component can be dropped into a React, Angular or plain-HTML page, and an Oracle Redwood one into an Oracle Cloud / Visual Builder application. See [Embedded UI](/java-user-manual/use-cases/embedded-ui/) for details. ## Native renderers Beyond the browser, Mateu also supports native renderers for desktop and mobile: | Renderer | Platform | Technology | |---|---|---| | [Desktop (IntelliJ plugin)](/native/) | Windows, macOS, Linux (inside IntelliJ IDEA) | IntelliJ platform / Swing | | [Mobile (React Native)](/native/) | iOS, Android | Expo / React Native | Both native renderers consume the same wire model as the web renderers, so web, desktop and mobile users can use the same UI at the same time. See [Native Renderers](/native/) for details. ## Bring your own If none of the available renderers fit, you can build your own frontend that consumes the Mateu API. See [Bring your own design system](/design-systems/bring-your-own-design-system/). --- # Accent colour and strip URL: https://mateu.io/design-systems/accent-strip/ > The decorative band an app gets from its accent colour in the Vaadin renderer: generated from @App(accentColor), your own image, or none. The **accent strip** is a thin decorative band in the app's brand colour, Mateu's take on Redwood's colour strip. The Vaadin shell draws it where Redwood draws its strip: under a page's header, on top of a listing's results and at the foot of the welcome hero. It says whose app this is, the way the accent colour does, and it never means "click here". ![The strip generated for #D2232A, seed 7](/images/docs/branding/accent-strip-D2232A-7.svg) :::note[Vaadin renderer only] Everything on this page applies to the Vaadin renderer. The Redwood renderer ignores `accentStrip`, `accentStripSeed` and the generated strip, and keeps showing its own Spectra strips. ::: ## Three ways to get a strip The strip follows the app's accent, `@App(accentColor)` (see [`@App` → Brand accent](/java-ui-definition/annotations/app/#brand-accent)). With no accent there is no strip at all. With an accent, `accentStrip` decides what the strip looks like. | `accentStrip` | The strip | |---|---| | blank (the default) | **Generated** by Mateu from the accent colour and `accentStripSeed` | | a URL, e.g. `"/images/strip.svg"` | **Your own image**, repeated along the strip | | `"none"` | **No drawing**: a plain band in the accent colour | ```java // generated: the default, nothing else to declare @App(accentColor = "#D2232A") // generated, another drawing in the same palette @App(accentColor = "#D2232A", accentStripSeed = 11) // your own image @App(accentColor = "#464c68", accentStrip = "/images/strip.svg") // a plain band, no drawing @App(accentColor = "#D2232A", accentStrip = "none") ``` Only a hex accent (`#rgb` or `#rrggbb`) can be drawn. Any other CSS colour, such as `rgb(210, 35, 42)` or `crimson`, still gives the plain band. ## How the strip is drawn The generated strip is an SVG, 1440×24 with `preserveAspectRatio="none"`. It uses Redwood's visual language: hills, arches, peaks and blocks overlapping along the width, with a dot texture on some hills and a dash texture on some blocks. Its colours are a palette derived from the accent in HLS (hue, lightness, saturation), where *L* and *S* are the accent's own values: | Colour | Derivation | Used for | |---|---|---| | base | the accent itself | the background | | dark | lightness × 0.78 | shapes | | ink | lightness × 0.42, saturation × 0.9 | the dot and dash texture | | four tints | for f = 0.15, 0.35, 0.58, 0.82: lightness L + (1 − L)·f, saturation min(S, 0.55)·(1 − 0.55·f) | shapes | | gold | HLS(42°, 0.69, 0.80), the same for every accent | shapes | | complement | HLS(hue + 180°, 0.71, 0.55) | shapes | The gold is always present because every Redwood strip carries one. The complement is the accent's opposite hue, kept soft. For `#D2232A` the palette is base `#d2232a`, dark `#a41b21`, ink `#551215`, tints `#c7565a` `#cf8386` `#dcb3b4` `#eee0e1`, and accents `#efc971` `#8cdeda`. For an indigo `#464c68` the same rules give a quieter strip: ![The strip generated for #464c68, seed 7](/images/docs/branding/accent-strip-464c68-7.svg) The shapes are placed by a seeded random walk. The same accent and seed always give the same strip, so the strip doesn't change between requests or restarts. Mateu draws it once per accent and seed, caches it, and sends it to the browser as a `data:image/svg+xml;base64,…` URI. ### Tiling without a seam The shell repeats the strip along the band and scales it to the band's height, keeping its proportions. At the shell's 10 px height a 1440×24 strip is 600 px wide, so a wide page shows two or three copies side by side. To make those copies join invisibly, the generated SVG tiles seamlessly: every shape that runs past the right edge is also drawn shifted left by the strip's width, and every shape that runs past the left edge is also drawn shifted right by it. Where one copy ends, the next continues the same shapes. Stretching a single copy across the page instead would only hide the seam up to some width, and would squash every shape sideways. This applies to the generated strip only. An image you declare with `accentStrip` is repeated as it is, so draw it to tile if the band is wider than the image. ## Picking a seed `accentStripSeed` defaults to 7. Another seed gives another arrangement of the same palette: ![Seed 7](/images/docs/branding/accent-strip-D2232A-7.svg) ![Seed 8](/images/docs/branding/accent-strip-D2232A-8.svg) ![Seed 11](/images/docs/branding/accent-strip-D2232A-11.svg) To choose one, export a few strips with the Java helper below, open them side by side and keep the seed you like. Some arrangements put a large gold or complement shape near the left edge, where it sits under the page title. If that is distracting, try the next seed. ## Exporting the SVG The generator is a public helper in `mateu-core`, `io.mateu.core.infra.AccentStrip`. Use it to keep the strip as a file, for example to serve it as a static image, to edit it by hand, or to use it outside Mateu: ```java import io.mateu.core.infra.AccentStrip; import java.nio.file.Files; import java.nio.file.Path; // 1440×24, the size Mateu uses Files.writeString(Path.of("strip.svg"), AccentStrip.svg("#D2232A", 7)); // another size (height of at least 11) Files.writeString(Path.of("strip-tall.svg"), AccentStrip.svg("#D2232A", 7, 1440, 48)); // the palette, to reuse its colours elsewhere AccentStrip.Palette palette = AccentStrip.palette("#D2232A"); // the data URI that the Vaadin shell receives String uri = AccentStrip.dataUri("#D2232A", 7); ``` An exported file can then be declared as the app's own image with `@App(accentColor = "#D2232A", accentStrip = "/images/strip.svg")`. ## On the wire `AppDto.accentStrip` carries only what the app declared, an image URL, or nothing for blank and `"none"`. The generated strip travels in a separate field, `AppDto.generatedAccentStrip`, that only the Vaadin shell reads. That keeps the Redwood payload exactly as it was. In the page, the strip reaches its places through the `--mateu-page-band-h` and `--mateu-page-band-image` custom properties on `mateu-app`, which an app's own CSS can also set. --- # Branding & design tokens (make it look like your brand) URL: https://mateu.io/design-systems/branding-and-design-tokens/ > How a Mateu app takes on a corporate brand through a token layer — and, honestly, where the declarative model ends and an escape hatch begins. The most credible criticism of a generated UI is *"will it look like our brand, or like the framework?"*. The honest answer has two parts: **most of it is a token layer you set once**, and the rest is an explicit, bounded escape hatch. This page covers both, so you can scope adoption with eyes open. ## The brand is a token layer, set once Because the UI is *declared* and the look lives in the renderer, branding is **CSS custom properties**, not per-screen work. Set them once and every generated screen is on-brand at once — no screen is touched. Mateu's production `mateu-vaadin` renderer themes through **Lumo variables** (`--lumo-*`), and Mateu's own components read those variables (with fallbacks), so a corporate theme is a set of Lumo overrides driven by your tokens. A worked example ships in the repo: [`frontend/reference-renderer/brand-theme.css`](/design-systems/reference-renderer/) themes a demo to a fictitious brand ("Acme") — a red `#D2232A` and a gold `#CA9C4E`. Its shape: ```css :root { /* 1 · brand tokens (once) */ --brand-red: #d2232a; --brand-gold: #ca9c4e; --brand-ink: #1f1a17; /* … */ /* 2 · map to Lumo → themes the production mateu-vaadin renderer */ --lumo-primary-color: var(--brand-red); --lumo-primary-text-color: #8f1418; --lumo-error-color: var(--brand-red); --lumo-border-radius-m: 10px; --lumo-font-family: var(--brand-font-body); } ``` Run the [reference renderer](/design-systems/reference-renderer/) and flip the **Theme** switch to see the *same wire* rendered default vs. branded — the proof that brand is a layer, not a rewrite: | Default | Brand tokens applied | |---|---| | ![Default theme](/images/docs/branding/brand-demo-default.png) | ![Brand theme](/images/docs/branding/brand-demo-brand.png) | Nothing in the definition changed between the two — only the token layer. **Proven at scale:** Wefox ran on Mateu with its own corporate design system in production. ### Logos & fonts (bring your own asset) Colour and type are tokens; the **logo is your trademark** — drop the official asset into the app shell's `logo` slot rather than committing it to the framework. Corporate **webfonts** are licensed assets: point the `--…-font-*` tokens at your self-hosted font. (The example uses safe fallbacks and a placeholder wordmark, on purpose.) ## Where the token layer ends — the escape-hatch playbook Tokens cover **visual style** (colour, type, spacing, radius). They do **not** cover **novel structure, non-catalogue widgets, or bespoke micro-interactions/animation** — that is the honest ceiling of any declarative model (production server-driven UI at Airbnb/DoorDash is layout-level by design too). For those, Mateu has explicit, relegated escape hatches. Reach for the smallest one that fits: | Need | Hatch | Cost | |---|---|---| | One field looks/behaves specially | **custom field** (stereotype + a web-component) | small; still declared | | A one-off widget on a screen | **`Element`** (arbitrary custom element + attrs + events) | small; hand-written markup behind a Mateu node | | Render a non-Mateu domain object as UI | **`ComponentAdapter`** | medium; you own the adapter + its round-trip | | A whole screen must be bespoke | **custom renderer** for that component type in your DS | larger; you own that renderer surface | | A pinch of client behaviour | **`run-js`** | small; last resort | Every hatch **forfeits generation for that surface** (you now maintain code there) — which is exactly why they are the exception, not the entry cost. See [Escaping the framework](/java-user-manual/advanced/escaping-the-framework/) and [Component adapter](/java-ui-definition/interfaces/component-adapter/). ## Scope guardrail (the decision rule) State, in the adoption decision, which surfaces are in scope for Mateu — this turns a real gap into a bounded, accepted risk: - **Operational / back-office / internal tools** (CRUD, forms, wizards, dashboards, check-in, folios): declarative + theme. The gap here is negligible and the velocity payoff is largest. **Default yes.** - **Brand-consistent customer-facing** with standard components: declarative + theme + the occasional custom field. - **Design-led / marketing / booking flows** with bespoke motion and pixel-perfect art direction: escape hatch or keep hand-coded. **Default: out of scope for generation** — use Mateu where it wins. Decision rule in one line: *consistent & operational → declarative + theme; bespoke & brand-led → escape hatch or hand-coded.* ## Before adopting: prove it against your brand Do this once, early, and the severity of the "design gap" stops being an opinion: 1. Build your **token layer** (map your palette/type to `--lumo-*`). 2. Reproduce **2–3 representative screens** spanning the spectrum: one operational (expected easy) and one deliberately design-led candidate. 3. Measure how much lands via the theme vs. needs an escape hatch — and write down the scope guardrail from what you find. --- # Bring your own design system URL: https://mateu.io/design-systems/bring-your-own-design-system/ > Build a custom Mateu frontend using your own design system or component library. Mateu's frontend and backend communicate through a simple, documented JSON API. Any frontend that implements this API becomes a valid Mateu renderer. ## How it works The Mateu backend exposes **one** sync endpoint per mount. A renderer POSTs the current route and any user action to it, and gets back a UI increment to apply: ``` POST /{baseUrl}/mateu/v3/sync/{route} Body: { "route": "...", "actionId": "<the load action> | <methodName>", "componentState": { ... } } ``` That is the canonical spelling (see [The exchange](/reference/wire-specification/#the-exchange)): the request body decides, so older spellings such as `…/mateu/v3/components/_/action` are still served the same way. The response is a `UIIncrementDto` carrying `commands` (navigation, window title, …), `messages` (toasts/alerts) and `fragments` (the component tree to render or patch). The same increment shape drives every interaction, so a renderer only ever implements one request/response. A renderer: 1. POSTs the route with the load action to get the initial `fragments` 2. renders the fragments using its own component library 3. sends user interactions back as further actions (the method's `actionId` + `componentState`) 4. applies the response — `fragments`, `commands` and `messages` See the [renderer contract](/design-systems/renderer-contract/) for the authoritative wire spec (exact action ids, component types and the increment schema). ## Starting point Clone one of the existing renderer repositories and adapt it to your component library. The [Vaadin renderer source](https://github.com/miguelperezcolom/mateu) is the most complete reference implementation. ## When to use this - You want Mateu UIs to match your company's proprietary design system - You are embedding Mateu in a platform with its own mandatory component library - You want to render Mateu UIs in a non-browser environment (native mobile, desktop) ## Related - [Design systems overview](/design-systems/) - [Embedded UI](/java-user-manual/use-cases/embedded-ui/) - [API](/mateu-about/api/) --- # Figma design-to-code URL: https://mateu.io/design-systems/figma/ > Design screens in Figma with the Mateu component library and generate the Java/C#/Python implementation through modux. **Status:** 🚧 In progress — the contract, the library generator plugin and the modux importer exist; the code generation templates are the next step. ## The idea A designer composes screens in Figma using a **Mateu component library** (Lumo/Vaadin flavor), and a generator turns those designs into working Mateu views — no hand-off, no re-implementation: ``` contract.json ──► Figma plugin ──► Mateu library ──► designer composes screens └─────────► modux importer ◄── Figma REST API (reads the composed screens) └──► modux model (pages) ──► Java / C# / Python ``` The key is the **design contract** (`design/figma/contract.json` in the Mateu repo): every Mateu component appears once, with its Figma component name (`Mateu/<Category>/<Name>`), variant axes named exactly like the Mateu annotation parameters (`theme`, `slim`, `propertyList`…), the text layers that map to labels/titles, and a `#config` line for ids (`fieldId=email; actionId=save`). Both ends read it: the Figma plugin **builds** the library from it, and modux's importer maps the designs **back** through it. ## What exists today - **The contract** — 64 components: the full Mateu catalog (fields, sections/zones, Notice, StatusList, EntityHeader, wizard + stepper, crud listing + smart filter bar, dashboards, gantt, kanban, app shells…). - **The library generator** — a Figma plugin (`design/figma/plugin`) that creates the whole library programmatically: run it once inside Figma, publish the file as a team library, re-run whenever the catalog grows. - **The importer** — modux's `importfigma` use case downloads a Figma file through the REST API and turns every top-level frame into a page of the modux model, with the Mateu instances (and their variants, texts and config) as its content tree. ## The full flow, step by step 1. **Generate the library** (once, and whenever the catalog grows): open Figma, import `design/figma/plugin/manifest.json` as a development plugin, run *Mateu Library Generator* on an empty file and publish it as a team library. 2. **Design**: the designer composes screens using only instances from the library — one top-level frame per screen. Variants select the styled knobs (`theme`, `propertyList`, `gridLayout`…), text layers carry the labels/titles, and the small `#config` line the ids (`fieldId=email; actionId=save`). 3. **Bring the design into the repo**: download the file JSON — ```bash curl -H "X-Figma-Token: $FIGMA_TOKEN" \ https://api.figma.com/v1/files/<FILE_KEY> > src/main/figma/screens.json ``` 4. **Generate the code** with the Maven plugin (modux repo, `figma-maven-plugin`): ```xml <plugin> <groupId>io.mateu.modux</groupId> <artifactId>figma-maven-plugin</artifactId> <version>0.1.0-SNAPSHOT</version> <executions><execution><goals><goal>generate</goal></goals></execution></executions> <configuration> <basePackage>com.acme.frontoffice.ui</basePackage> <languages><language>java</language><language>csharp</language><language>python</language></languages> </configuration> </plugin> ``` Every designed frame becomes a view class under `target/generated-sources/figma` (the Java ones join the compilation automatically): fields with their `@Label`s and `@Section`s (propertyList/frameless/zones), notices, texts, bulleted lists, separators and buttons come out ready; rich display components and wizard/crud frames come out as annotated skeletons with `TODO`s for the developer to finish. 5. **Alternatively, import into the modux model** (`importfigma` use case) when the screens should live in a full modux specification (aggregates, use cases, sagas…) rather than as standalone views. ## What's next Deepening the emitters (wizard steps, crud detail wiring, dashboards) and the modux generation templates consuming the imported content trees for the full-model path. See `design/figma/README.md` in the repository for the designer conventions and the detailed pipeline documentation. --- # Oracle Redwood URL: https://mateu.io/design-systems/oracle-redwood/ > Mateu renderer built on Oracle's Redwood design system. The Oracle Redwood renderer is built on **Oracle Visual Builder** — it renders Mateu screens with the Redwood design system's `oj-*` components (served from Oracle's CDN) inside a Visual Builder app. Use it when your UIs need to match Oracle Cloud applications or will be embedded inside existing Oracle Redwood interfaces. :::note This is the current Redwood/Visual-Builder line. The earlier standalone Oracle JET renderer (`redwood-oj`) has been [retired](/design-systems/renderer-contract/). ::: :::caution[Oracle licensing] The renderer's own code is Mateu's (Apache 2.0) and the jar **vendors nothing from Oracle**. At run time it loads from Oracle's CDN: - **Oracle JET and the Redwood theme** — open source, [UPL 1.0](https://www.oracle.com/downloads/licenses/upl-license1.html). - **The Spectra components (`oj-sp-*`), the Visual Builder runtime and Oracle's icon/illustration gallery** — Oracle's property, **not** open source. Their use is governed by **your own Oracle terms** (typically the Visual Builder entitlement of an Oracle Cloud subscription). Mateu grants no rights over them. Think of this renderer as a connector: the code is free; the service it connects to is not. Using it outside an Oracle subscription is a question for your Oracle agreement, not for Mateu's licence. The full statement ships in the jar as `META-INF/NOTICE.md` (and in the repository under `frontend/web/monorepo/apps/redwood/`). Oracle, Oracle JET, Redwood and Visual Builder are trademarks of Oracle and/or its affiliates; Mateu is not affiliated with or endorsed by Oracle. ::: ![A form rendered by the Redwood renderer](/images/docs/design-systems/basic-form-redwood.png) **Demo:** https://redwood.mateu.io/ Redwood's RDS toolkit standardizes full-page **templates** (Collection Detail, General Overview, Guided Process, Create and Edit — Drawer…). Mateu builds those templates from the UI model — see the [page templates map](/ux-patterns/page-templates/) for the template → archetype mapping. ## Two modes, one renderer | | **Standalone** | **Embedded** | |---|---|---| | What it is | A complete Visual Builder app (shell, menu, routes) in the `redwood` jar | `<mateu-ui>`, a JET Custom Component you import into **your own** Visual Builder app | | Who owns the page | Mateu: the URL is the Mateu route, the shell is Mateu's | Your VB app: its shell, its navigation, its URL; Mateu fills one area of a page | | JET / Redwood / Spectra | Loaded from Oracle's CDN by the packaged app | **Your app's** — the component brings no second runtime and no iframe | | How you get it | Maven dependency | `mateu-ui-<version>.zip` (attached to each release) | Both paint the same screens with the same code: the component's view **is** the standalone app's content page and it runs the same action chains, so a screen looks and behaves the same in both. ## Add to your project (standalone) ```xml <dependency> <groupId>io.mateu</groupId> <artifactId>mateu-redwood</artifactId> <version>3.0-beta.7</version> </dependency> ``` ## Embed Mateu screens in an existing Visual Builder app Use this when the shell already exists — a Fusion extension, a VB app your team owns — and some of its pages should show screens that a Mateu backend serves (a listing, a form, a wizard, a whole CRUD). ### 1. Import the component Download `mateu-ui-<version>.zip` from the [release](https://github.com/miguelperezcolom/mateu/releases) (or build it: `npm run build:embedded` in `frontend/web/monorepo/apps/redwood` → `build/embedded/mateu-ui-<version>.zip`). In Visual Builder: **Components → + (Import Component)**, pick the zip. It lands under `resources/components/mateu-ui/`; Visual Builder adds it to the Components palette and to the page's imports when you drop it on a page (or add it by hand to the page JSON: `"imports": {"components": {"mateu-ui": {"path": "resources/components/mateu-ui/loader"}}}`). ### 2. Drop it on a page ```html <mateu-ui base-url="https://erp.acme.com/mateu" route="{{ $variables.mateuRoute }}" params="[[ { id: $variables.orderId } ]]" app-context="[[ { company: $application.variables.company } ]]" headers-provider="[[ $functions.mateuHeaders ]]" on-mateu-navigate="[[ $listeners.mateuNavigate ]]" on-mateu-title="[[ $listeners.mateuTitle ]]"></mateu-ui> ``` **Properties** | Property (attribute) | Type | What it does | |---|---|---| | `baseUrl` (`base-url`) | string | The Mateu UI mount: its API is `<baseUrl>/mateu/v3/…`. Empty = the page's own origin. | | `route` | string | The Mateu route, relative to the mount (`orders`, `orders/:id`). Empty = the app's home. **Written back** when the screen navigates inside the component — bind it with `{{ }}` to follow it. | | `params` | object | Fills the route's `:placeholders`; the rest travel as the query (a listing opens filtered by them). | | `initialState` (`initial-state`) | object | The component state the first load of the screen is sent with (a form opens pre-filled). | | `appContext` (`app-context`) | object | The app state (`@AppContext`: company, hotel, fiscal year…) sent with every request. Changing it reloads the screen. | | `token` | string | Sent as `Authorization: Bearer <token>` (a value with its own scheme, `Basic …`, as is). | | `headers` | object | Extra headers for every request (tenant, correlation id…). | | `headersProvider` (`headers-provider`) | function | `(url) => headers` or a Promise of them, called on **every** request — the way to pass a token that rotates. Wins over `token`/`headers`. | | `withCredentials` (`with-credentials`) | boolean | Sends the browser's cookies to a backend on another origin. | | `navigation` | `internal` \| `host` | Who handles a navigation the **screen** asks for (a row click, an action returning a route, a link). See below. | Changing `route`, `params` or `initialState` opens that screen; `appContext` reloads the current one; `baseUrl`/`withCredentials` start over; a new `token`/`headers`/`headersProvider` is simply used from the next request on. Methods: `navigate(route, params)` and `reload()`. **Events** (JET convention: the type is camelCase, a page listens with `on-mateu-…`; all bubble) | Event | `detail` | When | |---|---|---| | `mateuNavigate` | `{route, force}` | The screen asks for another route. **Cancelable.** | | `mateuAction` | `{actionId, parameters}` | The user ran a Mateu action. | | `mateuTitle` | `{title}` | A new screen title — the page title is yours: show it where your page wants it. | | `mateuMessage` | `{summary, message, type, displayMode}` | A message for the user (also shown inside the component). | | `mateuReady` | `{route}` | The first screen is painted. | | `mateuError` | `{kind, message, status}` | A request failed (also shown in the component's error band). | **Navigation.** With `navigation="internal"` (the default) the screen navigates inside the component and `route` is written back; `mateuNavigate` fires first, and a listener that calls `event.preventDefault()` keeps the component where it is — for example to open the route in another page of your flow instead. With `navigation="host"` the component never navigates by itself: it only fires `mateuNavigate`, and your page decides (navigate its flow, or set `route`). Your page's URL is never touched either way: the component does not use the browser history. ### 3. Identity (your app's user on the Mateu backend) The component calls the Mateu backend from the browser, so the backend must be able to tell who the user is. Pass the identity your VB app already has: - **A bearer token your app holds** (OAuth/IDCS/OCI IAM token, a JWT from your gateway): bind `token="[[ $variables.accessToken ]]"`, or — if it rotates — use `headers-provider` with a page function, so it is read on every request: ```js // the page module (main-page.js), bound as headers-provider="[[ $functions.mateuHeaders ]]" define([], () => { let accessToken = ''; class PageModule { // call it from the action chain that obtains/refreshes the token (your security provider, // a service connection to your IdP…) setAccessToken(token) { accessToken = token; } // asked on every request (it is passed as a plain function: do not rely on `this`) mateuHeaders(url) { return { Authorization: 'Bearer ' + accessToken }; } } return PageModule; }); ``` - **Cookies** (the Mateu backend is behind the same SSO and shares the session cookie): `with-credentials="true"`, and on the backend `mateu.cors.allow-credentials=true` for your origin. On a `401` the component dispatches the cancelable `mateu-session-expired` event on `document` (`detail: {retry, giveUp}`): refresh the token in your app and call `detail.retry()` — the request is sent again once, with whatever your provider answers then. ### 4. CORS on the Mateu backend A VB app is served from another origin (`https://<instance>.oraclecloud.com`), so allow it: ```properties mateu.cors.allowed-origins=https://myinstance-vb.builder.ocp.oraclecloud.com # only with with-credentials="true": mateu.cors.allow-credentials=true ``` See [configuration](/java-create-your-project/configuration/#cross-origin-access-cors). ### What the component does not do (limitations) - **One `<mateu-ui>` per page.** The renderer core is a module with page-level state; a second instance on the same page takes over from the first (a warning is logged). - **No app shell.** The Mateu App's menu, header actions, `@AppContext` pickers, notification bell, AI chat and Ask palette are shell chrome: the host page has its own. Pass the context with `app-context`; navigate with `route` or your own menu. - **Dialogs, drawers and toasts** open in JET's popup layer over the page, as any JET overlay of the host does. - **Requirements on the host page:** JET 16–19 with the Redwood theme, the Spectra components (`oj-sp`, present in every Redwood VB app) and the Redwood icon font. On a plain JET page (not VB) the component points the missing `oj-sp`/`oj-dynamic`/`oj-oars` module paths at Oracle's CDN. - **Licensing:** the zip contains only Mateu code (Apache 2.0) — no file from Oracle. Inside your VB app it runs on your app's JET, Redwood and Spectra, i.e. entirely under **your** Oracle agreement. ### Manual test plan (a real Visual Builder instance) The component is verified in CI-like conditions against a plain JET host page (JET 18.1 from Oracle's CDN, `e2e/vb-embedded-probe.mjs`), not inside the Visual Builder designer. In a VB instance: 1. Backend: run a Mateu app (e.g. `demo/demo-vb`) reachable from the browser over HTTPS, with `mateu.cors.allowed-origins=<your VB app origin>`. 2. Import `mateu-ui-<version>.zip` (Components → Import). Expect it in the palette under *Mateu UI*, with its properties in the Properties pane. 3. On a new page drop the component; set `base-url` to the backend and `route` to `products`. Run the app (Preview): the listing renders with your app's Redwood look, no console errors. 4. Click **New**: the create drawer opens over the page; fill *Name*, **Save**: the row appears. 5. Bind `route` to a page variable with `{{ }}`, add a button that sets it to `person`: the form renders; edit *Name*, **Save**: the message shows. 6. Add an event listener for `mateuNavigate` (on-mateu-navigate) that logs `$event.detail`; on the person form click **Go to products**: the listener runs and the listing renders inside; the page URL does not change. Set `navigation` to `host`: the listener runs and the form stays. 7. Identity: protect the backend with your IdP; pass the token (`token` or `headers-provider`): requests carry `Authorization` (browser network tab) and the screens load; with an expired token the `mateu-session-expired` event fires. 8. Design time: the component should render (or show an empty box) in the designer canvas without breaking the page — it only calls the backend when it has a reachable `base-url`. ## Characteristics - Modern Oracle Cloud look and feel - Designed for data-dense enterprise UIs - Builds the RDS page templates (Smart Search, Collection Detail, General Overview, Guided Process…) from the same archetypes as every other renderer ## Related - [Design systems overview](/design-systems/) - [Embedded UI](/java-user-manual/use-cases/embedded-ui/) --- # The reference renderer (write your own in a day) URL: https://mateu.io/design-systems/reference-renderer/ > A minimal, dependency-free renderer for the Mateu wire — the concrete proof that a Mateu UI is portable, and the starting skeleton for your own renderer or design system. Writing a renderer has looked like an open-ended commitment. It is not: the wire is bounded, the [Core level](/design-systems/renderer-contract/) is small, and there is now a **minimal, dependency-free reference renderer** you can read in one sitting and start from. It lives at `frontend/reference-renderer/` — one HTML file and one JS module, **no framework and no build step**. It renders a Mateu UI using nothing but the wire itself, which is exactly why it is the concrete proof of [portability](/mateu-about/portability-and-exit/): if a ~250-line file with no dependencies can render the definition, the definition is genuinely portable. ## Run it ```bash cd frontend/reference-renderer python3 -m http.server 8090 # open http://localhost:8090, set Backend to a running Mateu app (any Java/.NET/Python server), pick a route ``` ## The whole protocol, in four steps A renderer is a function from `UIIncrementDto` to painted UI plus a way to post actions back. That is all: 1. **One call.** `POST {backend}/mateu/v3/sync/{route}` (route in the path, `_no_route` when empty) with a body of `{ route, actionId, componentState, appState, parameters, … }`. The route load is `actionId: ""`. The response is a `UIIncrementDto` (see the [wire specification](/reference/wire-specification/)). 2. **Apply the envelope.** Run `commands` (`SetWindowTitle`, `navigateTo`, …), show `messages`, then apply the `Replace` `fragments`. 3. **Walk the tree.** Each node's real type is `metadata.type`; a `Card`'s content is in `metadata.content`; a `FormField` carries `fieldId` / `label` / `dataType` / `stereotype` / `options`; values come from the fragment `state` / `initialData`. 4. **Post actions back.** A button posts its `actionId` with the current `componentState`; the response is another increment, applied the same way. ## Reaching Core, then stopping (or not) Core is a **usable renderer**: forms, field types, validation, actions, CRUD listings, text. When every Core fixture renders with no `<mateu-unsupported>` placeholder, you are Core-conformant — a legitimate, complete answer. Standard (sections, tabs, zones, wizards, filtering, master-detail) and Full (charts, uploads, islands, adapters) are where you keep going if you want to. Declare what you support (`SUPPORTED_TYPES` in the module) so the report can tell *"this type is not supported"* apart from *"this type broke"* — only the second is a bug. ## Scope & honesty This is a **teaching / proof artifact**, not a first-party product renderer. It implements Core; it does not do overlays (`Add` fragments), the full command set, the client fetch plan for external REST sources, or the rich catalogue. The first-party [conformance harness](/design-systems/renderer-contract/) drives renderers built on the shared `libs/mateu` plumbing; this standalone renderer shows the wire→DOM mapping directly, and wiring it into that harness is a follow-up. See `frontend/reference-renderer/README.md`. --- # Renderer contract URL: https://mateu.io/design-systems/renderer-contract/ > What a renderer has to implement to be a Mateu renderer — and the conformance levels that tell you when you are done. Mateu's contract is the wire: any server can serve any renderer. This page is the other side of it — what a **renderer** must do — and, more importantly, **when it is finished**. That second part is the one that has been missing. Four first-party web renderers were built and retired (SAP UI5, Redwood-OJ, PatternFly, SLDS), which is not a run of bad luck: *one renderer per design system, maintained in first person, does not survive a single maintainer*, because the cost is proportional to the number of design systems in the world. The way out is not more first-party renderers — it is making yours cheap enough to own. ## What a renderer does A renderer receives `UIIncrementDto` and paints it. Concretely: | It must | Detail | |---|---| | **Paint components** | walk the component tree and render each `type`; fall back to an explicit *unsupported* placeholder rather than silently dropping — that placeholder is what conformance measures | | **Honour commands** | the increment carries `commands` (`SetWindowTitle`, `navigateTo`, `closeModal`, `dispatchEvent`…) | | **Show messages** | `messages` are toasts/alerts, including the undoable ones | | **Apply fragments** | an increment is a set of partial updates targeted by `targetComponentId`, not a full repaint | | **Post actions** | a button, a row click or a trigger posts back with the current `componentState` | | **Execute the fetch plan** | `optionsSource`, `rowsSource`, `restAction`, `restData` are fetched **client-side** from arbitrary endpoints — a renderer that ignores them shows empty selects and empty listings with no error | | **Resolve routes** | in [bundle mode](/deploy/static-bundle/), from the shipped [route registry](/concepts/routes-and-mounts/) | And one thing it must **not** do: invent UI. Everything painted comes from the declaration; see [the authoring rule](/authoring-rule/). ## Conformance levels "Paint the whole catalogue" is not something a third party can act on, and it is why writing a renderer has looked like an open-ended commitment. So the surface is split into three levels, and **a level is reached when every fixture at that level renders with no unsupported placeholder, and every level below it does too**. | Level | What it buys | Fixtures | |---|---|---| | **Core** | A Mateu app *works*. Forms, field types, validation, actions, CRUD listings, text. | 7 | | **Standard** | A back office is *pleasant*. Sections, tabs, accordions, zones, multi-column, badges, banners, KPIs, wizards, filtering, master-detail. | 12 | | **Full** | The rich catalogue and the extension points. Charts, uploads, embedded islands, component adapters. | 4 | **Core is a usable renderer.** Stopping there is a legitimate, complete answer — a renderer that reaches Core and says so is more useful than one that claims everything and is half-finished in places nobody has mapped. ## Measuring yours The suite drives your renderer against the shared fixture app and detects the `<mateu-unsupported>` placeholders your fallback emits: ```bash cd e2e ./conformance.sh --renderer my-renderer # wires your dev server to the SUT ``` It writes `conformance-report/<renderer>/report.md` with the level reached, what is failing at the next one, and a screenshot per fixture. The console ends with the answer you actually want: ``` Conformance level reached: STANDARD ✓ core: 7/7 ✓ standard: 12/12 ✗ full: 2/4 — missing: mixed-chart, adapter ``` Publish that number. A renderer that declares **Core** honestly is contributable; one that leaves the question open is not. ## Declaring partial support A renderer publishes what it supports through `ComponentRendererSingleton.set`, and the report reads it (`__mateuRendererInfo.supportedTypes`). Declaring a subset is not a defect — it is how the report tells *"this type is not supported"* apart from *"this type broke"*, and only the second is a bug. --- # SAP Fiori / UI5 (retired) URL: https://mateu.io/design-systems/sapui5/ > The SAP UI5 renderer was retired; this page only keeps old links working. :::danger[Retired renderer] The SAP UI5 renderer was **retired**. There is no `sapui5-lit` artifact to depend on and no source app behind it. The supported web renderers are [Vaadin](/design-systems/vaadin/) and [Oracle Redwood](/design-systems/oracle-redwood/); see the [parity matrix](/reference/parity/). ::: ## If you used it Replace the renderer dependency with one of the supported ones — your `@UI` classes, YAML definitions and backend code do not change, because every renderer consumes the same wire model: ```xml <dependency> <groupId>io.mateu</groupId> <artifactId>mateu-vaadin</artifactId> <version>3.0-beta.7</version> </dependency> ``` If what you need is a look that matches an existing SAP Fiori launchpad, the [bring-your-own design system](/design-systems/bring-your-own-design-system/) guide describes how a renderer is built against the [renderer contract](/design-systems/renderer-contract/). ## Related - [Design systems overview](/design-systems/) - [Migrating from alpha](/reference/migrating-from-alpha/) --- # Vaadin URL: https://mateu.io/design-systems/vaadin/ > Mateu's default renderer, built on Vaadin Lumo web components. The Vaadin renderer is Mateu's default frontend. It uses Vaadin Lumo web components and works with Spring Boot, Quarkus, Micronaut, and Helidon. ![A form rendered by the Vaadin renderer](/images/docs/design-systems/basic-form-vaadin.png) **Demo:** https://vaadin.mateu.io/ ## Add to your project ```xml <dependency> <groupId>io.mateu</groupId> <artifactId>mateu-vaadin</artifactId> <version>3.0-beta.7</version> </dependency> ``` This is the renderer used in all Mateu quickstart guides and examples. ## Characteristics - Clean, professional look suited for business applications - Full component coverage: forms, grids, dialogs, notifications, charts - Light and dark mode support - Accessibility-first ## Related - [Design systems overview](/design-systems/) - [Bring your own design system](/design-systems/bring-your-own-design-system/) - [Quickstart](/java-user-manual/start-here/quickstart/) --- # Mateu URL: https://mateu.io/ > Define business UIs once, agnostically: one model, authored as YAML, in a visual editor or in Java, C# or Python; rendered on web, mobile and desktop; served by any backend or as a static bundle with none. import { Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components'; {/* UX: the hero answers "what is this?" in two seconds; the reel comes right after as the proof — never as a gate the value proposition hides behind. */} ## See it in 30 seconds <div style={{ maxWidth: '920px', margin: '1.5rem auto 0', aspectRatio: '16 / 10.2', borderRadius: '16px', overflow: 'hidden', boxShadow: '0 30px 90px -40px rgba(0,0,0,.6)' }}> <iframe src="/reel.html" title="Mateu — a 30-second tour" loading="lazy" allow="autoplay" style={{ width: '100%', height: '100%', border: 0, display: 'block' }}></iframe> </div> ## One model, three ways to write it :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The same product listing, written three ways. Each produces the same model, and every renderer draws it the same way. <Tabs syncKey="authoring"> <TabItem label="YAML (no code)"> ```yaml # specs/ui/products.yaml type: Listing title: Products searchable: true rowsSource: ref: products # an endpoint named once in sources.yaml columns: - {type: GridColumn, id: name, label: Name} - {type: GridColumn, id: price, label: Price} - {type: GridColumn, id: status, label: Status, dataType: status} ``` Write it by hand, or let the visual editor in IntelliJ or VS Code write it. </TabItem> <TabItem label="Java"> ```java @UI("/products") @Title("Products") public class Products extends AutoCrud<Product> { @Override public CrudStore<Product> store() { return ProductStore.INSTANCE; } } ``` </TabItem> <TabItem label="C#"> ```csharp [UI("products"), Title("Products")] public class Products : Crud<Product> { public override IEnumerable<Product> Fetch(string? search) => Store.Search(search); public override Product? Get(string id) => Store.Get(id); public override void Save(Product p) => Store.Save(p); public override void Delete(string id) => Store.Delete(id); } ``` </TabItem> <TabItem label="Python"> ```python @ui("products") @title("Products") class Products(Crud[Product]): def fetch(self, search): return store.search(search) def get(self, id): return store.get(id) def save(self, entity): store.save(entity) def delete(self, id): store.delete(id) ``` </TabItem> </Tabs> ![Products list](/images/docs/admin-panel/products-list.png) [Choose your path →](/start-here/choose-your-path/) ## The problem Most business applications end up as two applications: ```text backend → API → frontend → duplicated model → duplicated validation ``` That means duplicated concepts, duplicated validation, glue code, and one more project to keep alive. ## The Mateu approach ```text model (YAML · visual editor · Java · C# · Python) → one wire model → browser · phone · desktop ``` You declare what a screen contains; Mateu derives the screen. The model is files in your repository, reviewed and released like any other code — not a project in somebody's cloud. <CardGrid> <Card title="Author it your way" icon="pencil"> YAML and the [visual editor](/define/yaml/visual-editor/) with no code, or [Java](/java-user-manual/start-here/quickstart/), [C#](/csharp-user-manual/) or [Python](/python-user-manual/) — or [both on one screen](/define/mixing/). </Card> <Card title="Render it anywhere" icon="laptop"> [Vaadin](/design-systems/vaadin/) and [Oracle Redwood](/design-systems/oracle-redwood/) on the web (also embedded in Visual Builder apps), the [Mateu mobile app](/native/react-native/), and [IntelliJ](/native/) on the desktop. </Card> <Card title="Serve it from anything" icon="rocket"> [A backend](/deploy/) in Java (5 frameworks), .NET or Python — or a [static bundle](/deploy/static-bundle/) on a CDN with no backend. </Card> <Card title="Compose it" icon="puzzle"> [Federate](/mateu-about/ui-federation/) UIs owned by different teams and domains into one console. </Card> </CardGrid> ## What a Mateu UI is made of Whichever way you write it, a Mateu UI is built from the same blocks: a **mount** at a base path, an **app shell** and its **menu**, **routes**, **pages** (layouts of components, with optional **partials**), **actions**, **data sources** and the **state** they fill, plus the cross-cutting **field types**, **translations**, **environments**, **access** rules and **project settings**. [What a Mateu UI is made of](/concepts/building-blocks/) shows them on one diagram, with a small product catalogue as the running example. What those blocks look like to the people using the app (the shell, the six page types, the component catalogue and how to extend it) is the [UX guide](/ux/). ## What you can build <CardGrid> <Card title="Admin panels" icon="document"> CRUD-heavy backoffice screens over your model or your APIs. </Card> <Card title="Consoles over APIs" icon="external"> A 100 % static UI over REST APIs, the way cloud consoles are built. </Card> <Card title="Distributed backoffices" icon="puzzle"> Each service or domain owns its UI; a shell composes them. </Card> <Card title="Embedded UI" icon="seti:html"> Mateu screens inside React, Vue, Angular, Visual Builder or plain HTML. </Card> </CardGrid> Wondering how this differs from a React SPA, Vaadin or a low-code platform? See [Mateu vs the traditional stack](/mateu-about/comparison/) and [Mateu vs visual builders](/mateu-about/comparison-low-code/). ## Where to go next 1. [Choose your path](/start-here/choose-your-path/) — authoring, rendering, deployment. 2. A quickstart: [YAML](/define/yaml/quickstart/), [Java](/java-user-manual/start-here/quickstart/), [C#](/csharp-user-manual/) or [Python](/python-user-manual/). 3. [What a Mateu UI is made of](/concepts/building-blocks/) — the building blocks, on one map — then the rest of the [concepts](/concepts/). 4. [The UX guide](/ux/) — the structure of an app, the six page types, the components, and how to extend them; [The Mateu Way](/the-mateu-way/) shows where each page type starts in code. 5. [Serve & deploy](/deploy/) — backends, static bundles, Netlify, Kubernetes, app stores. --- # Kotlin URL: https://mateu.io/kotlin-user-manual/ > Use Mateu from Kotlin on the JVM with the Java @UI annotations. You can obviously use Mateu with Kotlin. The only thing you have to take care of is about configuring the annotation processor in the kotlin plugin. ```xml <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <configuration> <args> <arg>-Xjsr305=strict</arg> </args> <compilerPlugins> <plugin>spring</plugin> </compilerPlugins> </configuration> <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-allopen</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> <executions> <execution> <id>kapt</id> <goals> <goal>kapt</goal>  </goals> <configuration> <sourceDirs> <sourceDir>src/main/kotlin</sourceDir> <sourceDir>src/main/java</sourceDir> </sourceDirs> <annotationProcessorPaths>  <annotationProcessorPath> <groupId>io.mateu</groupId> <artifactId>mateu-annotation-processor-mvc</artifactId> <version>3.0-beta.7</version> </annotationProcessorPath> </annotationProcessorPaths> </configuration> </execution> </executions> </plugin> ``` Other than that, you just need your java classes with Mateu's annotations: ```kotlin @UI("") class Hello { } ``` You have a sample project in https://github.com/miguelperezcolom/mateu/tree/master/demo/demo-vaadin-kotlin-mvc --- # About Mateu URL: https://mateu.io/mateu-about/ Mateu is a model-driven UI system for building business applications and internal tools: you declare the model — in code (Java, C# or Python) or in YAML — and Mateu derives the UI, served by a backend or shipped as a static bundle. This section explains what Mateu is, why it was built, and how to think about it. Start here if you are evaluating Mateu or need to understand it from the ground up. ## In this section - [What is Mateu?](/mateu-about/what-is-mateu) — the core idea in plain terms - [Why Mateu](/mateu-about/why-mateu) — the problem it solves and what you gain - [How Mateu works](/mateu-about/how-mateu-works) — mental model, building blocks, and the stateless cycle - [Technical architecture](/mateu-about/architecture) — how the Mateu system is structured internally - [Mateu and system architecture](/mateu-about/system-architecture) — where Mateu fits in your backend design - [Comparison with traditional stacks](/mateu-about/comparison) — side-by-side contrast - [Status](/mateu-about/disclaimer) — current state of the project ## Next - [Build a full backoffice in 10 minutes](/build-a-full-backoffice-in-10-minutes) - [Create your first Mateu project](/java-create-your-project) --- # Advanced topics URL: https://mateu.io/mateu-about/advanced/ These topics cover more advanced usage patterns in Mateu. ## Topics - routing and parameters - UI federation - embedding - custom renderers - microservices composition ## When to read this Read this section after you understand: - how to define UIs (in YAML, with the visual editor, or in code) - how Mateu renders them - how routing and actions work ## Related pages - [UI federation](/mateu-about/ui-federation) - [Embed](/mateu-about/embed) - [Mateu in microservices](/mateu-about/microservices) - [Routing and parameters](/java-user-manual/concepts/routing-and-parameters/) --- # API URL: https://mateu.io/mateu-about/api/ Mateu's API is intentionally small and generic. The goal is not to make you design a custom API for every screen. The goal is to let a renderer talk to your backend UI definitions through a simple protocol. ## Why that matters This keeps frontend and backend decoupled while avoiding the overhead of hand-building application-specific UI APIs. ## Full spec You can explore the current API spec here: https://editor.swagger.io/?url=https://mateu.io/openapi/mateu.yaml --- # Architecture URL: https://mateu.io/mateu-about/architecture/ Mateu has three layers: a UI definition model, a small API (or a static bundle) that delivers it, and a renderer that turns it into a UI — in a browser, in the IDE or on a phone. ```text Your UI model (YAML / visual editor, or a ViewModel in Java, C# or Python) -> UI definition (the Mateu wire model) -> Mateu API (HTTP endpoints) — or a static bundle, with no backend -> Renderer (web components, IntelliJ plugin, React Native app) ``` These layers are decoupled. You declare the UI once. Mateu produces the definition. The renderer consumes it. ## The UI definition layer Mateu reads your UI model — YAML definitions (written by hand or with the visual editor), or ViewModels in code (fields, methods, annotations) — and produces an internal UI description. This description is a structured representation of: - what fields exist and their types - what actions are available - how the layout is structured - what validation rules apply - what navigation entries are exposed This description is the contract between whatever serves the UI and whatever renders it. It is not HTML. It is not JSON for a specific component library. It is an abstract UI specification. ## The API layer Mateu exposes a small set of HTTP endpoints that the renderer calls: - fetch the UI description for a given path - hydrate a ViewModel with current field values - execute an action - resolve a lookup (relationship options and labels) These endpoints are registered automatically by the Mateu integration for your runtime (Spring Boot, Micronaut, Quarkus, Helidon MP, ASP.NET, FastAPI). You do not write them. A UI with no server-side behaviour can skip this layer entirely: it is exported as a [static bundle](/deploy/static-bundle/) and served from a CDN. ## The renderer The reference renderer is a JavaScript web component (`<mateu-ui>`). It loads the UI description from the API, renders it using a configurable design system, and handles browser interactions — field binding, validation display, button clicks, navigation. Because the renderer consumes an abstract UI description, it can be replaced. Any client that speaks HTTP and understands the Mateu component tree can serve as a renderer: - **Web renderers** — JavaScript web components built on different design systems: Vaadin Lumo and Oracle Redwood (on Visual Builder). - **Desktop renderer** — an IntelliJ IDEA plugin that renders native Swing controls inside the IDE (tool windows, editor tabs, docking) on Windows, macOS, and Linux. - **Mobile renderer** — an Expo / React Native application that renders native components on iOS and Android. All renderers consume the same API. The same UI — and the same backend, when there is one — serves web, desktop, and mobile clients simultaneously. ## Stateless request cycle When a backend serves the UI, each browser interaction follows the same stateless path: ```text 1. Browser sends: current field values + action id 2. Mateu instantiates the ViewModel 3. Mateu hydrates it from the request 4. Mateu executes the action 5. Mateu serializes the updated UI definition 6. Browser renders the result ``` No session. No server-side UI state. The ViewModel is created per request and discarded after the response. ## Pluggable integration When a backend serves the UI, Mateu integrates with its runtime through an adapter layer. On the JVM, the same ViewModel code works across: - Spring Boot MVC - Spring WebFlux - Micronaut - Quarkus - Helidon MP The integration registers the Mateu API endpoints and handles DI for ViewModel construction. The C# (ASP.NET) and Python (FastAPI) ports emit the same wire model, and a UI defined only in YAML is served by any of them — or by none, as a static bundle. ## Orchestrators Orchestrators are the entry points for structured UI patterns. `AutoCrud` and `Crud` are orchestrators for CRUD flows. An orchestrator coordinates: - which ViewModel to use for listing - which ViewModel to use for viewing - which ViewModel to use for editing - which ViewModel to use for creation - which adapter handles data access and mutations ## Related - [Mateu and system architecture](/mateu-about/system-architecture) — where Mateu fits in hexagonal and DDD designs - [How Mateu works](/mateu-about/how-mateu-works) — how ViewModels become UI definitions - [Design systems](/design-systems) — available renderers and how to bring your own --- # Mateu vs traditional stack URL: https://mateu.io/mateu-about/comparison/ The difference between Mateu and a traditional stack is not a matter of tooling — it is a matter of where the UI definition lives and how many times you have to say the same thing. ## A concrete scenario Imagine adding a `discount` field to an order management screen. **Traditional stack:** 1. Add `discount` to the domain model 2. Add `discount` to the API response DTO 3. Add `discount` to the OpenAPI spec 4. Add `discount` to the TypeScript interface 5. Add the field to the React form component 6. Add validation to the frontend form 7. Handle the updated API response in the frontend state Seven steps. Multiple files across two codebases. **Mateu:** 1. Add `discount` to `OrderEditor` with `@DecimalMin("0")` One step. One file. ## Side-by-side comparison | Concern | Traditional stack | Mateu | |---|---|---| | UI definition | frontend components (JSX / templates) | Java ViewModel class — or the same model [authored as YAML](/define/yaml/pages/) | | Validation | frontend library (Zod, Yup, etc.) + backend | Bean Validation, once | | Routing | frontend router (React Router, etc.) | `@UI` (mounts) + `routes.yaml` (inner routes) | | Navigation | frontend nav config | `@Menu` annotations | | Relationships | frontend API call + state | `@Lookup` + backend supplier | | Browser feedback | frontend toast / notification library | return `Message` from action | | Model | backend model + API DTO + frontend type | one Java class | | Integration point | the browser (one API call + token per data source) | the server (client speaks one protocol with one endpoint) | | Deployment | backend + frontend build + CDN | one Java application | | Scaling | stateful sessions or session replication (in some cases) | stateless, no affinity | | Design system | bundled into frontend | pluggable renderer | ## What the traditional stack is still better at Consumer-facing products with complex animations, highly custom interactions, and brand-specific visual design benefit from a dedicated frontend application. Frontend frameworks give experienced teams precise control over the user experience. Mateu does not try to compete with this. The target is the class of applications where the frontend split is cost without commensurate benefit. ## The other comparison Screens can also be authored as data and edited visually, which puts Mateu next to a different set of tools — Oracle Visual Builder, OutSystems, Retool and friends. That comparison turns on where the model lives and what happens when you outgrow the tool: see [Mateu vs visual builders](/mateu-about/comparison-low-code/). ## When to choose Mateu Choose Mateu when: - the audience is internal (employees, operators, admins) - the UI is primarily data-driven (lists, forms, filters, actions) - the team is backend-heavy and frontend expertise is limited or expensive - maintaining a separate frontend application is a burden rather than an asset - you need to ship fast and keep maintenance cost low ## When not to choose Mateu Do not choose Mateu when: - the product is consumer-facing and visual differentiation is important - the UI requires complex client-side state that goes beyond forms and lists - you need fine-grained control over animations, gestures, or real-time interactions - the team has strong frontend expertise and wants to use it ## The core tradeoff Mateu gives you speed and simplicity at the cost of frontend flexibility. For the right applications, that is an excellent trade. ## Related - [Why Mateu](/mateu-about/why-mateu) — the problem and what you gain - [Use cases](/use-cases) — types of applications where Mateu fits --- # Mateu vs visual builders URL: https://mateu.io/mateu-about/comparison-low-code/ > How Mateu differs from low-code and internal-tool platforms — by where the model lives, who decides at runtime, and what happens when you outgrow the tool. Mateu now has a component catalog with a published schema, screens authored as YAML and a visual editor. That puts it in the same conversation as Oracle Visual Builder, OutSystems, Mendix, Retool, Appsmith and Budibase — so it is worth being precise about where the overlap actually is. The overlap is the **authoring surface**. The difference is everything around it: where the model lives, who decides what happens at runtime, and what it costs you to leave. This is deliberately not a feature matrix. Feature lists change every quarter; the differences below are structural. ## Where the model lives A visual builder keeps your application in its own store — a project in its cloud, a proprietary file, a database only the platform reads. The tool is the way in and usually the only way in. A Mateu model is **files in your repository**: `.java` classes and `.yaml` definitions, next to the code they drive. They go through your pull requests, your code review, your branches, your CI, your release. The visual editor is one way to write those files; a text editor is another; both produce the same lines in the same commit. That single difference is what the rest of this page is downstream of. ## Who decides at runtime | | Visual builders | Mateu | |---|---|---| | Data access | connectors and bindings configured in the tool | your repositories, your use cases, your transactions | | Business rules | expressions and flows in the platform's runtime | your domain code, in your language | | Auth | the platform's model, mapped to yours | your framework's security, already in the request | | Where integration happens | the browser, per page | the server: one endpoint, one protocol | Mateu's runtime spine is a wire protocol between your backend and a renderer. The screen is derived from your model, but *what happens when the user presses the button* is a method you wrote, in the application you already had. ## When you outgrow it Every model-driven tool meets the same wall: one screen in forty needs to be something the templates do not cover. What matters is not whether it can be done, but **what you keep when you drop down** — if the answer is "rewrite it outside the tool", the savings on the other thirty-nine stop counting. In Mateu that screen builds its own component tree by hand and keeps its state, its actions, its validation, its routing and the surrounding app chrome. Those guarantees are pinned by a test on purpose, because a promise nothing checks erodes quietly. ## Leaving - The model is already in your repo — there is nothing to export. - `mateu-bundle:bundle` renders the declared screens into a static bundle a CDN serves. - `mateu-bundle:openapi` exports the same declarations as an OpenAPI document. - The wire protocol is documented and the renderer contract is public, so a renderer you write yourself is a supported path, not a hack. ## Backend language Visual builders are largely indifferent to what your backend is written in — you integrate with it over HTTP like any other client. Mateu goes the other way: the UI is defined **in** the backend, in Java, Kotlin, C# or Python, sharing its model and its validation. If you have no backend to speak of, that is not an advantage; if you have one and it owns the business rules, it removes an entire translation layer. ## What visual builders do better Plainly, because it matters when choosing: - **Non-developers can build screens.** Mateu's authoring surface is friendlier than it was, but its audience is still a team with a repository and a build. - **Batteries included** — hosting, user management, connectors to hundreds of SaaS products, environments and audit trails, all in the box. - **Free-form visual layout.** A WYSIWYG canvas positions anything anywhere. Mateu derives layout from the model and lets you adjust it; it is not a design tool. - **Governance for a large citizen-developer population** is a product feature there, and not something Mateu attempts. ## Choosing | Pick a visual builder when | Pick Mateu when | |---|---| | the builders are not developers | the builders own a backend | | the app is mostly connectors over SaaS data | the logic lives in your domain code | | you want hosting and governance in the box | you want the UI in the same repo, review and release as the code | | the screens are bespoke by design | the screens are forms, listings and workflows over your model | ## A note on Oracle Visual Builder VB is also a **target**, not only a competitor: one of Mateu's renderers is a Visual Builder application, so a Mateu backend can be served through the Redwood/VB runtime and its design system. See [Oracle Redwood](/design-systems/oracle-redwood/). ## Next - [The model](/mateu-about/the-model/) — what is actually being authored, and the rules that keep it honest - [Mateu vs the traditional stack](/mateu-about/comparison/) — the comparison with a hand-written SPA - [When to use Mateu](/when-to-use-mateu/) --- # Architecture diagram URL: https://mateu.io/mateu-about/diagram/ This is the shortest way to understand Mateu. ```mermaid flowchart LR A[Java classes, fields, annotations, actions] --> B[Mateu model] B --> C[Simple API] C --> D[Frontend renderer] E[Service A UI] --> F[Shell] G[Service B UI] --> F H[Service C UI] --> F F --> D ``` ## Read it like this - your backend code defines the UI model - Mateu exposes that model through a simple API - a renderer turns it into a real UI - multiple services can contribute UI modules to one shell ## Why it matters This is why Mateu fits so naturally with: - microservices - distributed systems - stateless architectures - internal tools and business apps --- # Status URL: https://mateu.io/mateu-about/disclaimer/ Mateu is actively developed. Version 3 is the current development line, with a focus on cleaner architecture, better components, and more extension points. ## Current state Some parts of the system are stable and usable in production scenarios. Others are still being refined. The best way to evaluate the current state is through: - the live demos - the quickstart examples - the Java user manual ## What to expect APIs may change between minor versions during active development. The core ViewModel model — fields, annotations, actions, orchestrators — is the most stable part. Integration-layer APIs (how Mateu registers with Spring Boot, Micronaut, etc.) are also stable. The renderer and design system integrations are more likely to evolve as new design systems are added and the web component implementation matures. ## Feedback If you find issues, gaps in the documentation, or behaviors that do not match what is described here, the project is open to contributions and feedback. ## Related - [What is Mateu?](/mateu-about/what-is-mateu) — start here if you are evaluating - [Build a full backoffice in 10 minutes](/build-a-full-backoffice-in-10-minutes) — a practical starting point --- # Embed URL: https://mateu.io/mateu-about/embed/ Mateu's reference frontend uses web components, which makes embedding straightforward. You can place a Mateu UI inside any page by loading the renderer script and using the web component. ## Why embedding matters Embedding makes Mateu useful beyond standalone apps. You can: - place a Mateu UI inside an existing website - expose only a specific route or form - compose multiple UIs in a larger application shell ## Basic example ```html <mateu-ui baseUrl="https://demo.mateu.io/fluent" config='{"tenantId":"1111","profile":"dev"}' top="false"> </mateu-ui> ``` ## Route-specific embedding If you want to embed only a specific part of the UI, you can pass a route. ```html <mateu-ui baseUrl="https://demo.mateu.io/fluent" route="/forms/counter1" top="false" style="width: 100%; height: 100vh;"> </mateu-ui> ``` ## Theming isolation An embedded Mateu app does **not** inherit the host page's design tokens, and does not repaint if the host changes them. This is not automatic from shadow DOM: shadow DOM encapsulates rules and selectors, but CSS *custom properties* (`--lumo-*`, `--mateu-*`) cross the shadow boundary by inheritance. A host that declares `--lumo-primary-color` on its own `:root` is an ancestor of `<mateu-ui>`, so without a firewall it would recolour every embedded component. Mateu firewalls the tokens by **proximity**: the renderer re-declares its full token baseline on the `<mateu-ui>` / `<mateu-ux>` container itself. Because the container is a *closer* ancestor than the host's `:root`, every element inside resolves each token from the container, and the host's value can never win. Dark mode still works: `<mateu-ui>` mirrors the document's `theme` attribute, so the scoped dark palette follows it. You get this for free — there is nothing to configure. A host page can style itself however it likes (including with its own `--lumo-*` tokens) without disturbing the embedded app. > One caveat: Vaadin overlays (dialogs, drawers, menus) render in the document body, outside the > `<mateu-ui>` container. When Mateu owns the page they inherit its document-scope tokens as usual; > in an embedding scenario an overlay may pick up the host's tokens. The app surface itself is fully > isolated. The behaviour is pinned by the browser probe `e2e/theming-isolation-probe.mjs` (drops a rogue `--lumo-primary-color` on the host `:root` and asserts it reaches a plain element but **not** the inside of `<mateu-ui>`) and the unit test `libs/mateu/.../theme/themeScope.test.ts`. ## Capability compatibility A host embeds an app served by a possibly-different backend, and a static bundle can outlive the renderer build a CDN serves it with. The honest compatibility question is not *"which version?"* but *"does the loaded renderer implement everything this app relies on?"* — so Mateu negotiates **by capability, not by version window**. :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Every app advertises, on `AppDto.requiredCapabilities` (and, for a static bundle, on `manifest.json`), the capability tokens it needs from its host renderer. Most are **derived** from the app's own metadata — it needs `command-center` because it opted into it, `sse` because it declared a streaming endpoint, `rest-sources` because it ships a source catalogue. You can declare extra ones for anything the derivation cannot see: ```java @App(requires = {"my-custom-widget"}) public class MyApp { … } ``` The renderer holds the set it **provides**. On boot the shell compares the two; if it is missing anything the app requires, it logs a clear warning and dispatches a `mateu-capability-mismatch` event (with the missing tokens) so a host can react — show its own message, load a newer renderer, or block. It never blocks rendering: a degraded screen the host is told about beats a silently broken one. A newer app needing a token an older renderer bundle does not provide is exactly what this catches — a version number could not, because it says nothing about which features a build actually implements. The token vocabulary (`io.mateu.uidl.Capabilities`, and its .NET/Python/`libs/mateu` mirrors) is a stable contract: adding a token is additive; existing tokens are never renamed or repurposed. ## Key idea Mateu UIs are not just pages. They can also be delivered as embeddable UI building blocks. --- # Governance and continuity URL: https://mateu.io/mateu-about/governance-and-continuity/ > The honest answer to 'it's a small project — what if the maintainer disappears?' — what AI changes, what it does not, and the mitigation package that makes the residual risk acceptable. The most legitimate objection to adopting Mateu is not technical, it is organizational: **it is a small open-source project with a small maintainer team.** A serious architecture committee will ask "what if the maintainer disappears?", and the honest answer is not a slogan — it is this page. This is the companion of [Portability & exit strategy](/mateu-about/portability-and-exit/): that page is about *leaving*; this one is about *staying safely* — who is accountable, and how the project does not die on you. ## The honest risk - **Maturity:** what ships is the **GA of v3, not v1** — the model has years in production across major versions (Quotravel, then Wefox's broker portal, the latter with its own corporate design system). The version number is accumulated iteration, not immaturity. - **But:** the ecosystem is small, the talent pool for "people who already know Mateu" is tiny, and the framework core is effectively stewarded by a small team. That is real and we do not paper over it. ## What AI changes — and what it does not AI genuinely changes the *shape* of this risk. It does not make it disappear. - **It neutralizes the "you need a community to use it" half.** Because the authoring surface is a small, open-source, AI-legible DSL, an AI plus a competent director can build missing application features on demand, self-serve usage support, and onboard people — without depending on ecosystem size or a hiring market for Mateu-specific skills. For *day-to-day adoption*, "no big community" is largely a non-issue. (See [Mateu and AI](/mateu-about/mateu-and-ai/).) - **It does not transfer accountability.** AI reduces the *labour* needed to steward the framework core; it removes **none** of the accountability, liability, security warranty, or deep design-intent ownership that a vendor or community implicitly provides. AI is a force multiplier on a steward, not a substitute for one — and unmanaged, AI can even *mask* the design-intent bus factor by confidently editing code no human still fully judges. > **Committee-proof framing:** AI turns *"we need a community to use it"* into a non-issue; it turns > *"we need someone accountable to steward it"* into a **governance requirement, not a labour problem** > — and that governance must be funded, not assumed. So the risk splits: **low on adoption, medium on core stewardship** — and the medium is acceptable *only if* the mitigations below are actually in place. ## The mitigation package ### 1. Open source + fork-readiness (the structural backstop) Mateu is Apache 2.0 (permissive, explicit patent grant). Continuity does not depend on upstream: keep a **buildable internal fork with its own CI**, pin the version you run, own the build. If upstream stops, you are already running your own code. See [Portability & exit strategy](/mateu-about/portability-and-exit/). ### 2. The definition is a portable asset you own Your UI is declarative data in your repository, renderable by another engine (there is a [reference renderer](/design-systems/reference-renderer/) proving it). Your investment is not trapped in the runtime. See [the wire specification](/reference/wire-specification/). ### 3. At least two people who can *judge* the core The real bus factor is not "can code be written" (AI covers that) but "is there a human who understands the design intent well enough to **accept or reject** an AI-proposed change and catch a plausible-but- wrong one." Mitigation: **≥2 people** able to judge framework/mapper/port changes, and **human sign-off required** on any core/mapper/port change. This is the single most important item. ### 4. An architecture & invariants guide Make ownership *transferable*: formalize the framework's cross-cutting invariants and known failure modes (the hard-won "gotchas") into a maintainer's guide, so a second steward can ramp up and AI output can be checked against written invariants rather than tribal knowledge. ### 5. A support / ownership charter (name who is answerable) A committee needs a responsible party. Choose one, explicitly: - **Commercial support agreement with the maintainer** — turns the author into an accountable vendor with an SLA; or - **Internal ownership charter** — the adopting organization names the internal team/owner answerable for the framework as deployed. Either is fine; *unstated* is not. ### 6. Periodic independent security review AI plus a single author cannot self-certify security. Commission a **periodic external audit** of the framework as deployed. (Mateu already runs CodeQL and ships a11y/RBAC by construction, but that is not a substitute for independent review at adoption scale.) ## What this asks of an adopting organization Governance is a **funded commitment**, not a free property of open source: - Allocate/provide the **second steward** (or fund the maintainer relationship that supplies judgement). - Stand up the **internal fork + CI** and the **version-pinning** discipline. - Choose and sign the **support/ownership charter**. - Budget the **periodic security audit**. Do these, and "small OSS project" moves from an unmanaged risk to a managed one. Skip them, and a committee is right to treat the risk as material — which is exactly why they are stated here rather than hidden. ## Decision points (maintainer / adopter) - Who are the **≥2 core judges**, and what is the sign-off rule? - **Support model:** commercial SLA vs internal ownership charter? - Who commissions and pays for the **security audit**, and how often? - Where does the **architecture & invariants guide** live, and who keeps it current? --- # How Mateu works URL: https://mateu.io/mateu-about/how-mateu-works/ > The mental model, building blocks, and stateless cycle behind Mateu UIs. The shift Mateu requires is not technical — it is conceptual. You are not building screens. You are defining a model that becomes a UI. This page explains the model through its **code** form (Java), where state, actions and structure are fields, methods and annotations. The same three concepts exist in a YAML definition (fields, actions bound to sources or a view model, layout) and in C# and Python — see [Define the UI](/define/). ## Three concepts Everything in Mateu maps to three things: **State** — the fields that describe the current situation. **Actions** — the methods that change it. :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: **Structure** — annotations that control layout, routing, navigation, and rendering behavior. ```java public class OrderEditor { // state String orderId; OrderStatus status; List<OrderLine> lines; // action @Button public Message confirm() { confirmOrderUseCase.handle(new ConfirmOrderCommand(orderId)); return new Message("Order confirmed"); } } ``` That class is a complete UI definition. Mateu produces the form, the button, the validation, and the browser feedback from it. ## From definition to UI Mateu works in three steps: ```text ViewModel (Java class) -> UI definition (Mateu internal representation) -> rendered UI (browser) ``` You only write the ViewModel. Mateu introspects its fields, methods, and annotations to produce a UI description. The renderer turns that description into a working browser interface. ## Stop thinking in pages Traditional frontend development starts with a page. You design the page, then you wire it to the backend. In Mateu, you start with the model. The page is a consequence of the model, not the starting point. When you need a product management screen, do not ask "what does this screen look like?" Ask "what is the state of a product, and what can you do with it?" ```java public record Product( String id, String name, BigDecimal price, ProductStatus status ) implements Identifiable {} ``` That question — answered in Java — is the UI definition. ## Building blocks ### Routing `@UI` registers a class as a UI root at a given path. Mateu wires the routing automatically. ```java @UI("/products") public class ProductsRoot { ... } ``` ### State — field types Fields on a ViewModel class become form fields. Their Java type determines the input: | Java type | Default input | |---|---| | `String` | text field | | `int` / `Integer` | number field | | `boolean` / `Boolean` | checkbox | | `LocalDate` | date picker | | `LocalDateTime` | date-time picker | | `enum` | select / dropdown | | `List<T>` | grid or checkbox group | Override the default with `@Stereotype`. ### Actions Any method annotated with `@Button` becomes a clickable action. Returning a `Message` sends a browser notification. Returning any Java object navigates to it as a new view. ```java @Button public Message submit() { saveOrderUseCase.handle(command); return new Message("Saved"); } ``` Actions belong to the backend. The button in the browser is just a signal — the backend decides what it means. ### Validation Mateu uses Bean Validation. Constraints are enforced in the browser before the action fires, and again on the backend. ```java @NotEmpty String name; @Min(1) int quantity; @Email String contactEmail; ``` ### Layout A few annotations control how fields are arranged: - `@Section("Shipping")` — groups fields under a heading - `@Colspan(2)` — makes a field span two columns - `@Zones` / `@Zone` — side-by-side column layout - `@Tab` / `@FoldedLayout` — tabbed groupings, or sections side by side ### Navigation `@Menu` exposes a field or nested class as a navigation entry. Nesting `@Menu` fields produces a tree. ```java @UI("/admin") public class AdminRoot { @Menu OrdersMenu orders; @Menu ProductsMenu products; } ``` ### Relationships `@Lookup` resolves foreign keys through backend suppliers — plain Java classes that can call any query service or repository. ```java @Lookup(search = ProductOptionsSupplier.class, label = ProductLabelSupplier.class) String productId; ``` The browser does not know how to resolve the relationship. It asks the backend. The backend returns options. The browser displays them. ### AutoCrud and Crud For standard business entities, `AutoCrud` gives you a full CRUD flow from a single class: ```java @UI("/orders") public class Orders extends AutoCrud<Order> { @Override public CrudStore<Order> store() { return new OrderStore(); // your CrudStore<Order> } } ``` When you need explicit control, `Crud` lets you define each screen separately: ```java public class OrdersOrchestrator extends Crud< OrderView, OrderEditor, OrderCreationForm, OrderFilters, OrderRow, String> { ... } ``` ## The stateless cycle Mateu does not store UI state on the server between requests. Each browser interaction follows this path: ```text 1. browser sends: current field values + action id 2. Mateu instantiates the ViewModel 3. Mateu hydrates it from the request 4. Mateu executes the action 5. Mateu serializes the result as a UI definition 6. browser renders the result ``` ViewModels are plain Java classes with no server-side lifecycle. They are created, used, and discarded per request. ## What you define — full reference | Concept | How | |---|---| | State | fields | | Actions | methods annotated `@Button` or `@Toolbar` | | Validation | Bean Validation (`@NotEmpty`, `@NotNull`, `@Size`, …) | | Layout | `@Colspan`, `@Section`, `@Zones`, `@Tab`, `@FoldedLayout` | | Routing | `@UI` (mounts), `routes.yaml` (inner routes) | | Navigation | `@Menu` | | Rendering intent | `@Stereotype` | | Relationships | `@Lookup` | | Dynamic rules | `@Rule`, `@Hidden` | | Browser feedback | return `Message`, navigate by returning any object | ## What you do not do - write HTML or JSX - configure frontend routes - write API clients - manage frontend state - duplicate validation - synchronize models across layers ## Next - [Technical architecture](/mateu-about/architecture) — how the Mateu system is structured internally - [Mateu and system architecture](/mateu-about/system-architecture) — where Mateu fits in DDD and hexagonal designs - [Build a full backoffice in 10 minutes](/build-a-full-backoffice-in-10-minutes) — a complete worked example --- # Mateu and AI: why not just generate React? URL: https://mateu.io/mateu-about/mateu-and-ai/ A fair question in the age of capable coding assistants: *why use Mateu at all — why not let the AI build the whole UI, e.g. in React?* Posed as "Mateu **or** AI", the question is already lost — it sounds like defending a framework against a tide. The useful question is **what you ask the AI for**. Framed that way, Mateu doesn't compete with AI; it **relocates** it. ## Two worlds, two artifacts **AI generates React.** The artifact the AI produces is the *final code*: thousands of lines of JSX, hooks, state, client-side validation. That is what someone reviews, versions, maintains, and regenerates every time the domain changes. **AI generates the metamodel (Mateu).** You ask the AI for the *intent* — an annotated class — and a deterministic renderer downstream materializes it. This is the determinism axis: **AI for intent→spec, a deterministic generator for spec→UI**. What changes is not *whether* you use AI, but **the size and risk of what the AI emits**. ## Why this matters (structural, not cosmetic) - **The review surface collapses.** Reviewing a 30-line metamodel is tractable; reviewing the equivalent generated React is not — and in practice nobody does, it gets approved on faith. - **Consistency becomes a system property.** 500 screens behave the same because they share one renderer, not because the AI got it right 500 times in a row. - **No double source of truth.** The domain lives in the backend; the UI is derived from it. A new field propagates by itself. Generated React gives you two representations of the same truth that someone must resync forever. - **You can enforce invariants.** On a typed metamodel you can layer validation (annotation processing, fail-fast, ArchUnit). On generated React there is no typed metamodel to hold on to. ### The counterintuitive part The **better** AI gets at generating React, the **stronger** the case for Mateu — not weaker. The marginal cost of *producing* code trends to zero, but the marginal cost of *trusting* generated code — reviewing it, maintaining it, guaranteeing it hasn't drifted — does not. AI solves the cheap problem and leaves the expensive one intact. Mateu attacks the expensive one. ## The layer above: coordinating the enterprise's UIs Building *one* screen — with AI or without — is the small problem. The big one is making **all** the UIs across an organization converge. That is a different league, and it is where Mateu stops being "a way to build a screen" and becomes the **layer that sets the rules** above the individual UIs: - **One contract (UIDL) + one renderer** — N teams and hundreds of screens behave the same because they share a renderer. Consistency is a *system property*, not something to get right screen by screen. - **A shared domain vocabulary** — company conventions are encoded once as composed (semantic) annotations (`@ProveedorId`, `@Importe`, …) and every screen inherits them. - **Standard ports / SPIs** — `CrudStore`, `Listing`, `Translator`, role-based security, i18n. Every element plugs in the same way, so cross-cutting rules apply uniformly. - **Federation** — Maven (build-time) and `RemoteMenu` / `MicroFrontend` (runtime) let many services and teams compose **one** coherent application, and the design system is governed in a single place. So the debate isn't really "AI or not": AI **generates the pieces**; Mateu **governs how they fit** — the contract, the vocabulary, and the composition that make an organization's UIs converge. That governance is exactly what generated-React-per-team cannot give you. ## The honest pushback No self-deception — the trade-offs are real: - **The expressive ceiling is real.** Every new pattern (list degradation, master-detail, filter bars) is work in the renderer. Mateu can only do what its vocabulary expresses. When you need an interaction the metamodel doesn't cover, you hit a wall; AI generating React has no such wall. If your competitive value is *differentiated UX*, Mateu is a cage. - **You own a framework.** "AI + React" outsources the renderer to the ecosystem; Mateu makes you the permanent owner of the renderer, the processor, and the metamodel. That is a real bus-factor question. - **AI is far better at React than at Mateu.** Millions of React examples in training, almost none of Mateu. In the React world the AI is your natural ally; in the Mateu world it is a beginner. That erodes part of the "AI emits the spec cheaply" promise. (Shipping AI reference files and skills — see [Use Mateu with AI assistants](/ai-assistant-reference/) — narrows this gap but does not erase it.) ## The dividing line Mateu wins when: - the UI domain falls mostly **within its vocabulary** — enterprise CRUD, forms, lists, master-detail; - you value **consistency and longevity** over maximum expressiveness; - the cost of the renderer **amortizes over hundreds of screens** and years of maintenance. For a startup whose product *is* the interface, the honest answer is: **don't use Mateu — let the AI generate React and pay the cost of maintaining it.** For a large, long-lived portfolio of business screens, that same cost is exactly what Mateu removes. See also [When to use Mateu](/when-to-use-mateu/) and [Why Mateu](/mateu-about/why-mateu/). --- # Mateu in microservices URL: https://mateu.io/mateu-about/microservices/ Each service owns its own UI. This is the core principle for using Mateu in a microservices architecture. ## Service-owned UIs In a microservices system, a common problem is UI ownership. Either: - a separate frontend team builds one large SPA that depends on all services, or - each service team builds its own frontend in isolation with no shared navigation Mateu offers a third option: each service defines its own UI as an inbound adapter, and a shell composes those UIs through federation. ## How it works :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Each service exposes a UI root: ```java // orders-service @UI("/orders-service") public class OrdersServiceRoot { @Menu OrdersCrud orders; @Menu OrderLinesOrchestrator lines; } ``` ```java // products-service @UI("/products-service") public class ProductsServiceRoot { @Menu ProductsCrud products; @Menu CategoriesOrchestrator categories; } ``` Each service is fully autonomous — it deploys independently, manages its own data, and owns its own UI logic. ## The shell composes them A shell application aggregates the service UIs through `RemoteMenu`: ```java @UI("/admin") @Title("Operations Console") public class ShellRoot { @Menu RemoteMenu orders = new RemoteMenu("/_orders-service"); @Menu RemoteMenu products = new RemoteMenu("/_products-service"); } ``` The shell does not know the internal structure of each service's menu tree. It delegates to the remote service's UI definition. The service controls what it exposes and how it is structured. ## Ownership model | Concern | Owner | |---|---| | Domain logic | each service | | UI definition | each service (its own ViewModels) | | Data access | each service (its own repositories and query services) | | Navigation composition | shell | | Authentication | shell (or shared infrastructure) | | Branding | shell | ## What this avoids This model avoids the two common failure modes: **The monolithic frontend** — a single SPA that must be updated every time any service changes its API. Changes to the orders service require a frontend deployment. Teams are coupled. **Isolated frontends with no shared shell** — each service has its own UI application with no consistent navigation or branding. Users switch between disconnected applications. ## Independent deployment Because each service owns its UI and exposes it through a remote menu endpoint, services can be deployed independently. The shell picks up changes at runtime — a new screen in the orders service is immediately visible in the shell without redeploying the shell. ## Related - [UI federation](/mateu-about/ui-federation) — how federation works in detail - [Shell and remote menus](/mateu-about/shell-and-remote-menus) — how to configure the shell - [Mateu and system architecture](/mateu-about/system-architecture) — where Mateu fits in distributed backend designs --- # Portability and exit strategy URL: https://mateu.io/mateu-about/portability-and-exit/ > What you own, how to self-host, and how to leave — the guarantees that make a Mateu UI a portable asset rather than a bet on one vendor. Adopting a UI framework is a long-term commitment, so the honest question a serious team asks is not "how good is it today" but **"what happens if the project is abandoned, and how do we leave?"** This page answers that directly. It is a first-class guarantee, not an afterthought. The short version: **your UI is a declarative definition — data you own and keep in your own repository — served by an open-source (Apache 2.0) runtime you can self-host indefinitely.** There is no proprietary project store to be locked out of, and there are three concrete exit routes. ## What you actually own - **The definition.** Your screens are `@UI` classes (Java/C#/Python) and/or YAML (`routes.yaml`, `sources.yaml`, layout definitions) living in **your** version control. There is nothing to "export" from a vendor cloud — the source of truth is already yours. - **The wire.** At runtime the backend emits a documented JSON model (`UIIncrementDto` and friends) with a generated JSON Schema of its own (`wire-schema.json`), and the authoring surface has published JSON Schemas too (component catalog, routes, sources, the unified specs schema) — all served from `backend/shared/uidl/*.json` on `master` (see the [wire specification](/reference/wire-specification/#the-machine-readable-schemas)). Four independent renderers already consume the same wire, and three backends (Java, .NET, Python) emit it — so "any server serves any renderer" is demonstrated, not asserted. - **The runtime.** Mateu is **Apache 2.0** — a permissive license with an explicit patent grant. You can run it, fork it, patch it and self-host it forever, with no license fee and no vendor runtime. ## The license guarantee (the backstop) Portability of the *definition* is moot if the *runtime* cannot be legally self-hosted after an abandonment. Mateu is licensed **Apache License 2.0** (`LICENSE.txt` at the repository root). That is a deliberate choice for corporate adoption: - **Permissive** — no copyleft obligations on what you build on top. - **Explicit patent grant** — the clause corporate legal and procurement look for. - **Self-hostable in perpetuity** — freeze a version, keep an internal buildable fork, own your build. This is not source-available or "open core": there is no revenue/seat threshold that flips it to a paid license. The whole runtime is under Apache 2.0. ## Three ways out If you ever need to leave Mateu, you have three routes, in increasing order of effort: ### 1. Self-host the open-source runtime (the default backstop) Because the runtime is Apache 2.0 and lives in your build, "the vendor disappeared" does not stop you: - **Pin the version** you are on; keep an internal, buildable fork with its own CI. - **Own the build** — the app is a normal Spring Boot / Quarkus / Micronaut / Helidon / ASP.NET / FastAPI service (see the per-framework guides under *Create your project*, and the demo `Dockerfile`s for containerization). Nothing about deployment depends on an upstream service. - Continuity is then **independent of upstream** — you are running your own code. ### 2. Ship the static bundle (no backend at all) For screens that are pre-renderable, `mvn -Pbundle package` (or `GET /mateu/v3/bundle`) produces a static SPA (`index.html` + `manifest.json` + assets) that a CDN serves **with no Mateu backend**. See [Static bundle](/deploy/static-bundle/). This subset of your UI outlives the runtime today. (Its limits: no server-side behaviour/secrets, and it depends on any external APIs being reachable from the client — see that page.) ### 3. Render the definition with another engine The wire model is documented and bounded, and the renderer surface is measured by a **conformance harness** (`e2e/conformance.*` against a shared set of fixtures) with three levels — **Core**, **Standard**, **Full**. The [renderer contract](/design-systems/renderer-contract/) states exactly what a renderer must do. So building a **Core-level** renderer for your frozen wire version is a bounded engineering task, not a rewrite of your application. (Full parity is a real project — Mateu itself has retired renderers — but Core is what "keep the lights on" requires.) ## Honest limits We would rather you read this than discover it: - **The value split.** The definition is declarative *intent*; the *behaviour* (layout inference, CRUD orchestration, filter/state semantics) is produced by the Mateu runtime. Migrating the definition to another engine means re-implementing those **derivation semantics**, which today live mostly in code and docs rather than in one formal spec. The static bundle sidesteps this for pre-renderable screens; anything with server logic does not travel as data alone. - **Not yet a versioned multi-vendor standard.** The wire is documented and schema-backed, but does not yet carry an explicit protocol version, and it evolves. It is re-implementable against a **pinned snapshot** — "freeze this wire version" is the supported procedure — but it is not (yet) a frozen public standard. Versioning the wire and publishing it as a standalone spec are on the roadmap (see below). - **Skills, not just files.** The definition has no vendor lock on the *files*, but the derivation runtime and the Mateu-specific skills are, today, effectively single-vendor. This is a materially better position than any proprietary low-code platform (which traps the app in its runtime), and a *different* trade-off than hand-built React (portable skills, but framework-coupled code and a hand-written API-for-the-UI). Choose with that framing, not on a slogan. ## Self-host runbook (pointers) A Mateu app is an ordinary backend service; deploy it the way you deploy any of these: - **Per-framework setup:** *Create your project* → Spring Boot MVC / WebFlux · Quarkus · Micronaut · Helidon MP (annotation-processor wiring included), plus .NET and Python guides. - **Containerization:** the `demo/demo-vaadin-*` modules ship multi-stage `Dockerfile`s (Maven build → runnable JAR → JDK 21 runtime) you can copy. - **Backend-free:** [Static bundle](/deploy/static-bundle/) for CDN deployment. ## Roadmap: making portability verifiable, not theoretical To move this page's guarantees from "true in principle" to "verifiable", the following hardening is planned (tracked as workstream **R2** in the reference-architecture materials): 1. **Version the wire** — an explicit `wireVersion`/`schemaVersion` on the envelope and in the schema `$id`, with an additive-within-a-major compatibility policy. 2. **Publish the wire + derivation semantics as a standalone versioned spec** (not scattered across DTOs and docs). 3. **A minimal Core reference renderer** — the concrete "1-day renderer" skeleton the conformance harness measures. Until those land, treat routes (1) and (2) above as fully available today, and route (3) as "bounded and documented, against a pinned wire snapshot". --- # See it in action URL: https://mateu.io/mateu-about/see-it-in-action/ The fastest way to understand Mateu is to try the live demos. ## Live demos - https://vaadin.mateu.io - https://redwood.mateu.io :::note The SAP UI5 and Redwood-OJ demos were removed along with those renderers (see the [parity matrix](/reference/parity/)). ::: ## What to look for As you explore the demos, pay attention to: - how much UI is generated from backend definitions - how interactions are handled without a traditional frontend app - how the same core ideas can be rendered with different frontend implementations ## Why the demo matters The demos also reflect one of Mateu's architectural strengths: stateless interaction and decoupled rendering. The frontend can remain static, while the backend handles UI state and behavior through Mateu's model. --- # Shell and remote menus URL: https://mateu.io/mateu-about/shell-and-remote-menus/ Mateu allows you to build a shell application that composes UI modules from multiple services. ## The shell The shell defines: :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: - authentication - branding - navigation - shared UI elements ```java @UI("") @Title("Console") public class ShellHome { } ``` ## Remote menus Remote menus allow the shell to include UI modules from other services. ```java @Menu RemoteMenu users = new RemoteMenu("/_users") .withServerSideType("..."); ``` Each remote menu points to a UI exposed by another service. The remote can be any Mateu app, including a product's console built with Mateu — see [Using external Mateu UIs](/java-user-manual/build/using-external-mateu-uis/) for CORS, tokens, deep links and wire versions across the two services. ### Where the shell asks a remote The shell itself calls each remote (server to server) to read its descriptor. Where that call goes is decided by **configuration only**, never by the request: - an **absolute** `baseUrl` (`https://forms.acme.com`) is asked as written; - a **relative** `baseUrl` (`/_users` — another path of the same deployment) is resolved against this server's own base url: the `mateu.self-base-url` setting (an origin, e.g. `https://shell.acme.com`), else what the adapter knows of its local socket (Spring MVC and WebFlux over plain http answer `http://localhost:<port>`). When neither is known the remote is treated as unreachable — set the property. | Property | Env var | Default | | --- | --- | --- | | `mateu.self-base-url` | `MATEU_SELF_BASE_URL` | unset (adapter's local socket) | | `mateu.remote.allowed-hosts` | `MATEU_REMOTE_ALLOWED_HOSTS` | unset (any http/https host) | | `mateu.remote.timeout-seconds` | `MATEU_REMOTE_TIMEOUT_SECONDS` | `30` | `mateu.remote.allowed-hosts` is an optional comma-separated allow-list (`forms.acme.com, orders.internal:8080`): when set, a call to any other host is refused. An entry without a port allows every port of that host; with one, it must match the port written in the url. A route appended to the remote's url can never leave `<baseUrl>/mateu/v3/sync/` (a `..` that would is refused). :::caution[Changed in 3.0-beta] A relative remote used to be resolved against the request's `Origin` header. Any non-browser client sets that header to whatever it likes, so the server could be made to POST to an internal host (server-side request forgery). If your shell relied on it behind TLS or on Quarkus/Micronaut/Helidon, set `mateu.self-base-url`. ::: ### Descriptor caching To build the navigation, the shell asks each remote for its descriptor (title, menu, home wiring). That is an HTTP round trip landing on the remote's home route, and it happens every time the shell resolves a route — the first of the two requests a user sees on every page change. The descriptor is app-shaped, not request-shaped: it only changes when the remote is redeployed. The shell therefore caches it briefly, keyed by the remote's base URL, route **and** the caller's authorization token (a remote is free to build a menu per user, so the token is part of the key, stored as a SHA-256 digest). | Property | Env var | Default | | --- | --- | --- | | `mateu.remote-menu.descriptor-ttl-ms` | `MATEU_REMOTE_MENU_DESCRIPTOR_TTL_MS` | `30000` | The TTL bounds how long a redeployed remote's new menu takes to appear in the shell, which is why the default is 30 s and not longer. Set it to `0` to disable the cache and ask on every navigation. The system property wins over the environment variable. ### How the menus are merged The browser asks every remote for its menu and puts each answer where its section is. A few rules keep the shell steady while that happens: - **One remote down is one section down.** The remotes are asked together and each answer is merged as it arrives. A remote that does not answer (within 20 s) leaves its section in the menu, dimmed, with a tooltip saying it is not available; it is asked again in the background (after 10 s, 30 s and 60 s) and whenever the user clicks the section. The rest of the menu, the page on screen and the app-wide connection banner are not affected. - **The shell's label wins.** When the shell declares a section's label — `@Label` on the field or `withLabel(...)` — that label stays, even after the remote answers with its own (when the remote answers with a single top-level entry, the usual "a group named after the service"). Without a declared label, the field name is shown until the remote answers, and then the remote's label replaces it, so a remote can still translate its own name. - **A declared label groups the remote's entries.** When the remote answers with several top-level entries and the shell declared the section's label, they go into a group (submenu) with that label, its icon and its path, in every variant — `HAMBURGER_SECTIONS` already made it a section. Pasted flat, each of the remote's pages (its own "Home" too) sat next to the shell's and the label was lost. Without a declared label they are still pasted in place: there is no name to give the group. Only the menu's shape changes: each entry keeps its route and its remote, so clicks, deep links and reloads reach the same screens as before. - **Route collisions are reported.** A remote's routes are relative to its own mount and are used as they are, so the shell's `/inicio` and a remote's `/inicio` are the same address and only one of them can be reached by it. When the shell and a remote, or two remotes, claim the same route, the browser console says so once, naming the route and both sources (`mateu: route collision — "/inicio" is claimed by the shell and by RemoteMenu "Library" (…)`). Nothing is overridden on purpose: give one of them a different route. - **The section is known before the remote answers.** Each remote section travels with the route prefix its screens live under: the remote's own path — its field name, `/forms` for `RemoteMenu forms`, wherever the shell groups it. So on a cold load the active section and the first breadcrumb ("Admin › Forms") are there on the first paint, and the rest of the trail follows when the remote answers. A deep link also says which remote it was mounted from, so a section whose field is named after something else (`workflowAdmin` serving `/workflow/...`) is found too. - **Hidden sections still place a page.** A `@Hidden` remote section is not drawn, but it stays in the navigation tree: a page under it gets its breadcrumbs. Its menu is fetched only while the user is in it. - **The variant is the app's.** A shell with remote sections used to be forced to `MENU_ON_TOP` in the browser. Now the declared variant is respected; `AUTO` (and a fluent `AppShell` with no variant) picks `MENU_ON_TOP` for such a shell, so an app that declares nothing looks the same. Both renderers apply the same rules: the web renderers through `navTree.ts` in `libs/mateu`, and Redwood through a port of it (`apps/redwood/poc/navTree.mjs`, its bridge cannot import TypeScript). ### Deep links A deep link that no local entry claims is resolved on the server. The shell picks the remote by **longest prefix** from what it already knows — the cached menus of its remotes (see below) and each remote's mount path — and asks only that one. Only when that tells nothing, or the chosen remote turns the route down, are the rest asked, all at once, and the longest claim wins. A remote that is down claims nothing; it no longer fails the shell's request. ## Ownership model - shell → composition - service → UI + logic ## Benefits - no frontend integration layer - independent deployment - clear boundaries - simpler architecture ## Mental model The shell is a container. Each service plugs its UI into it. --- # Standalone desktop app URL: https://mateu.io/mateu-about/standalone-desktop/ A Mateu UI is most often deployed as a web service: a backend (Java, C# or Python) serves the UI model and (optionally) the renderer, and users open it in a browser — or, with no backend at all, as a static bundle on a CDN. But the exact same application can also be packaged as a **self-contained desktop tool** the user just launches — with or without a browser. This is how internal utilities are often shipped: no deployment, no URL to remember, no separate install of a frontend. The user double-clicks a jar (or a native launcher) and a normal-looking desktop app appears. ## Two ways to run it as a desktop tool **Native desktop renderer — no browser.** Mateu ships an [IntelliJ plugin](/native/) that renders the app **inside IntelliJ IDEA** with native Swing components — tool windows, editor tabs, docking. There is no browser involved at all; the plugin speaks the same `/mateu/v3/sync` contract to the Mateu backend. It is the right fit when the users are developers or power users who already live in the IDE. **Web shell — browser + local server.** Alternatively, reuse the web renderer: run the normal Mateu web service on `localhost` and open the default browser pointing at it; the browser is the UI shell. In *this* mode it is a *local* server, not "no server" — everything runs on the user's machine, but the UI is a web page served over loopback HTTP. The rest of this page covers this web-shell setup; for the native path see [Desktop & Mobile](/native/). ## Web shell: the two ingredients 1. **Serve the renderer from the app itself.** Add a renderer dependency so the same service that exposes the API also serves the UI (see [how the renderer is served](/mateu-about/architecture/)). With `baseUrl=""` the frontend calls back to the very server hosting it — same origin, no CORS. ```xml <dependency> <groupId>io.mateu</groupId> <artifactId>mateu-vaadin</artifactId> <version>3.0-beta.7</version> </dependency> ``` 2. **Open the browser on startup.** Launch the default browser at the local URL once the server is ready. ## Opening the browser when the service starts :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: With Spring Boot, react to `ApplicationReadyEvent` and open the browser pointing at the port the app is listening on: ```java import org.springframework.beans.factory.annotation.Value; @Component class BrowserLauncher { @Value("${server.port:8080}") int port; @EventListener(ApplicationReadyEvent.class) void openBrowser() { openInBrowser("http://localhost:" + port); } static void openInBrowser(String url) { try { if (Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.BROWSE)) { Desktop.getDesktop().browse(URI.create(url)); return; } // Fallback for headless-ish desktops (Linux without AWT desktop) String os = System.getProperty("os.name").toLowerCase(); String cmd = os.contains("win") ? "rundll32 url.dll,FileProtocolHandler " + url : os.contains("mac") ? "open " + url : "xdg-open " + url; Runtime.getRuntime().exec(cmd); } catch (Exception e) { // The app still works — the user can open the URL manually. System.out.println("Open " + url + " in your browser."); } } } ``` ## Closing the app from a widget Because the UI is a Mateu screen, "quit" is just an action — and this works the same whether you run the native renderer or the web shell. Put a button (or a [`@Fab`](/java-ui-definition/annotations/), or a toolbar action) on a screen and shut the process down from it: ```java @UI("") @Title("Change Management Toolkit") public class Home { // ... your screens, menus, etc. @Fab(icon = "vaadin:power-off", label = "Quit") public void quit() { // Give the response a moment to reach the browser, then exit. new Thread(() -> { try { Thread.sleep(300); } catch (InterruptedException ignored) {} System.exit(0); }).start(); } } ``` For a cleaner shutdown you can close the Spring context instead of calling `System.exit` directly — inject `ApplicationContext` and call `SpringApplication.exit(context, () -> 0)`. ## When this fits This pattern shines for **internal, single-user tools** that benefit from a rich web UI but should not require infrastructure to run — for example a utility that generates the artifacts needed for a project's change-management process, a local data-munging console, or a setup wizard shipped alongside a larger product. You get the full Mateu programming model (declarative `@UI` classes, CRUDs, wizards, validation) with the distribution profile of a desktop app: one artifact, launched locally, closed by the user. --- # Mateu and system architecture URL: https://mateu.io/mateu-about/system-architecture/ The UI is an inbound adapter. This is the central architectural idea in Mateu, and it has practical consequences for how you structure your application. ## Inbound adapters In hexagonal architecture, inbound adapters are the entry points into your application: ```text Infrastructure / inbound -> REST controllers -> gRPC endpoints -> message consumers -> scheduled jobs -> UI <-- Mateu belongs here ``` Each adapter translates an external signal into a call to the application core. A REST controller translates an HTTP request. Mateu translates a browser interaction. This means a Mateu ViewModel can call: - application use cases directly - query services - ports and gateways - domain services without any additional API layer in between. The UI is a first-class consumer of the application core, not a downstream client of a REST API. ## What this removes Traditional internal tools are built with an API in the middle: ```text Backend -> REST API -> API client -> Frontend model -> Browser ``` That API exists primarily because the frontend is a separate application. When the UI is an inbound adapter, the API between frontend and backend becomes unnecessary for the internal UI. The ViewModel calls the application core directly. ```text Backend -> Mateu ViewModel (inbound adapter) -> Browser ``` The REST API still exists for external consumers. It is not replaced. It is just no longer the only way for the UI to talk to the backend. ## Domain alignment Mateu works well with DDD because ViewModels map naturally to domain concepts. :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: A `ProductEditor` ViewModel calls `SaveProductUseCase`. It does not call a generic `/api/products` endpoint that was designed to serve any consumer. It calls the specific use case that represents the intent. ```java @Override public void save(HttpRequest request) { saveProductUseCase.handle( new SaveProductCommand(id, name, price, status) ); } ``` This keeps the ViewModel aligned with the domain, not with a REST contract. ## CQRS alignment For listings, Mateu connects naturally to query services. ```java @Override public ListingData<ProductRow> search(SearchRequest request, HttpRequest httpRequest) { return productQueryService.findAll(request.searchText(), filters(request), request.pageable()); } ``` The list view calls the query side. The edit form calls the command side. The split is clean and explicit. ## Where validation lives Validation belongs in the domain — in value objects, aggregates, and use cases. Mateu enforces Bean Validation constraints in the browser as a user experience feature, but the authoritative enforcement happens in the application core. The ViewModel does not duplicate validation logic; it delegates to it. ## Microservices In a distributed system, each service can own its own Mateu UI. Services expose their UI through `@UI` roots. A shell application composes them using `RemoteMenu`. ```java @UI("/admin") public class ShellRoot { @Menu RemoteMenu orders = new RemoteMenu("/_orders-service"); @Menu RemoteMenu products = new RemoteMenu("/_products-service"); } ``` The shell does not know the internal structure of each service's UI. It only knows the remote URL. The service controls what it exposes. ## Summary | Concern | Owner | |---|---| | Domain logic | domain layer (aggregates, value objects) | | Use cases | application layer | | Data access | repositories and query services | | UI definition | Mateu ViewModel (inbound adapter) | | Rendering | Mateu renderer | ## Next - [Architecture](/mateu-about/architecture) — how the Mateu system is structured internally - [Why Mateu](/mateu-about/why-mateu) — what you gain from this approach - [Mateu in microservices](/mateu-about/microservices) — service-owned UIs and federation --- # The model URL: https://mateu.io/mateu-about/the-model/ > One UI model, several ways to author it and several things that consume it — plus the rules that keep them from drifting apart. A Mateu screen is not the Java class you happened to write it in. The class is **one way of saying it**. What travels on the wire, what the renderers paint, what the visual editor edits and what the static bundle exports is always the same thing: ```text a component tree + the routes that reach it + the shell around them ``` That is the model. Everything else in this page follows from it being a real model — something with a schema, several producers, several consumers and written-down rules — rather than a convenient shape for one library's API. ## Several ways to say the same thing | You author in | What it looks like | |---|---| | **Java / Kotlin** | `@UI` classes, annotations, fluent components | | **C# / Python** | attributes / decorators over the same catalog ([parity matrix](/reference/parity/)) | | **YAML** | [pages](/define/yaml/pages/), a [route registry](/concepts/routes-and-mounts/), an [app shell](/define/yaml/app-shell/) | | **Visually** | the visual editor, which writes YAML back into your repo | | **Design** | Figma, through the published `contract.json` ([design pipeline](/design-systems/figma/)) | :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The same screen, twice. In Java: ```java @UI("/orders") @Title("Orders") public class Orders extends AutoCrud<Order> { @Override public CrudStore<Order> store() { return new OrderStore(); // your CrudStore<Order> } } ``` As data — a page definition plus the entry that routes to it: ```yaml # specs/ui/orders.yaml type: VerticalLayout content: - type: Text text: Orders size: xl ``` ```yaml # specs/ui/routes.yaml routes: - route: orders definition: orders.yaml ``` Neither is the "real" one. They meet in the same model, and a screen can mix them: `@UISpec` takes its layout from YAML and its behaviour from Java, and a `layoutDelta:` records what a human rearranged on top of a layout the framework still infers on every request. ## Several things consume it - **Three server runtimes** — Java/Kotlin, C# and Python emit the same wire model. - **Every renderer** — two web design systems (Vaadin, Oracle Redwood), React Native on mobile, the IntelliJ plugin on the desktop. None of them knows how the screen was authored. - **The [static bundle](/deploy/static-bundle/)** — `mateu-bundle:bundle` renders your declared screens at build time into a `manifest.json` a CDN can serve. - **The [visual editor](/define/yaml/pages/#the-visual-editor-writes-these)** — reads the catalog straight from the generated schema, so it offers every component without anyone maintaining a second list. - **External tooling** — the Figma contract ships inside the `io.mateu:mateu-uidl` jar at `META-INF/mateu/contract.json`, so generators and importers read it from the artifact instead of keeping a copy that drifts. - **`mateu-bundle:openapi`** — the same declarations exported as an OpenAPI document. - **The [client-side expander](/concepts/routes-and-mounts/)** — turns a declarative page (a route with a `definition` and no view model) into the wire model **in the browser**, so the no-backend path renders without a server round-trip. - **A [static compiler](/design-systems/renderer-contract/)** — the same declarative page compiled **at build time into standalone HTML+CSS with no Mateu runtime** (the interpreter/compiler axis of rendering). Zero overhead, runs anywhere you can serve a file; it reuses the expander's model understanding and refuses a view-model route (that needs a backend). The catalog also carries two consolidations that keep reuse and extension in the same model rather than in code: a **[business component](/java-ui-definition/component-catalogue/)** is a named, bound composition of existing pieces referenced by name (`ComponentRef`) — it ports for free and resolves with no backend; a **[custom component](/java-ui-definition/custom-components/)** is a genuinely new rendering carried as data (`CustomComponent`), the explicit, relegated per-renderer escape hatch that degrades to a visible placeholder where a renderer has not registered it. ## What makes it a model and not a config format A format is a way to write things down. A model has to survive being written down by several people and read by several tools, which takes rules: **The catalog has a published schema, generated from the source of truth.** `uidl-schema.json` and `routes-schema.json` are generated from the records themselves and pinned by a test, so adding a component without regenerating fails the build instead of shipping a schema that does not know about it. Editors point their YAML IntelliSense at them. **Precedence is written down: authored wins.** The annotation processor's index and the authored `routes.yaml` are two producers of one route table. The authored half replaces the derived entry outright — and the same order applies on the server, in the browser and in the ports, because route resolution runs in more than one place. **Human decisions are stored as deltas, not snapshots.** A `layoutDelta:` anchors to field ids and is re-applied to a freshly inferred tree on every request, so a field the model grows later still lands in its inferred place. A `layout:` is a snapshot that takes the screen out of inference for good — and the editor shows which of the two a page is on, so the moment a screen leaves inference is visible rather than silent. **Inference cannot flip in silence.** `PageFingerprint` produces a stable per-class signature meant for golden tests, so a change to the inference rules shows up as a failing diff instead of a screen that quietly became a different template. ## Where the model stops Worth knowing before you plan around it: - **Rendering still goes through a server.** There is no client-side YAML renderer: a page authored as data is served through the ordinary sync path. The static bundle covers the **initial load of static routes**, precomputed at build time — live data comes from external endpoints and **actions still need a backend**. - **`layoutDelta:` is served by the Java server.** The C# and Python ports parse the key and decline the page rather than rendering it wrongly. - **The YAML app shell does not carry everything yet** — the flags read reflectively off an `@App` class (theme toggle, command center, `@AppContext` selectors, notifications, global search, FABs) still need that class. See [App shell as data](/define/yaml/app-shell/). - **The model is not meant to say everything.** When a screen needs to be something no template covers, you drop to a component tree and build it by hand — and what you keep when you drop down (state, actions, validation, routing, the surrounding chrome) is pinned by a test, because a promise nothing checks degrades. ## Next - [Mateu vs visual builders](/mateu-about/comparison-low-code/) — how this differs from a low-code platform - [Mateu vs the traditional stack](/mateu-about/comparison/) — how it differs from a SPA - [YAML UI definition](/define/yaml/pages/) — authoring pages as data - [Route registry](/concepts/routes-and-mounts/) — routes as data --- # UI federation URL: https://mateu.io/mateu-about/ui-federation/ Mateu lets multiple services contribute to a single UI. Each service can expose: - its own UI root - its own menu tree - its own CRUDs and screens A shell application can compose those modules using `RemoteMenu`. ## What this gives you - decentralized ownership - centralized navigation - no frontend integration layer - microfrontends without a traditional frontend application ## What the shell can own The shell can also centralize concerns such as: - branding - authentication - page metadata - shared widgets This makes it possible to compose a distributed UI while still keeping a consistent application shell. ## The two contracts a federated shell needs Federation works because what travels between a domain and the shell is a **declaration**, not a JS bundle: one renderer, one framework version, no CSS collisions. But two things then have to be agreed, and leaving them implicit is what turns a federated UI into a distributed mess. ### 1. Route ownership Routes declared inside a mount are **relative to it**, so two domains can each have an `orders` screen without colliding — uniqueness only has to hold *within* a mount, and between mount base paths (two `@UI` classes claiming the same base path already fail at startup). Within a mount, two classes claiming the same route is a bug. Mateu keeps **first-wins** — changing it would move which class answers a route in apps that already work — but "first" depends on classpath order, which is **not stable** between builds, or between a developer's machine and CI. So a collision is now **reported with both class names** at startup: ``` route collision: 'orders' is claimed by com.acme.billing.Orders and by com.acme.sales.Orders. Classpath order decides which one answers, and that order is not stable — give one of them a different route. ``` Re-declaring the same route for the *same* class is not a collision (an index can legitimately be read twice) and stays silent. ### 2. Version compatibility A federated deployment mixes jars: domain A may have been built against one Mateu version and domain B against another, while the shell runs a third. **The policy: all the jars in one shell must be built against the same Mateu MINOR version.** Patch differences are fine; minor differences are not supported, and nothing checks it for you today. That is not caution for its own sake — it follows from where the coupling actually is. A domain jar carries `@UI` classes compiled against `io.mateu:mateu-uidl` and an index written by that version's annotation processor; the shell's core reads both. Anything that changes the wire DTOs or the index format therefore has to be uniform, and Mateu is still `3.0-alpha`, where the wire is explicitly allowed to move. In practice: **bump Mateu across all your domain modules in one go.** If you cannot, keep the straggler behind its own mount and a separate deployment rather than mixing it into a shared shell. ### Embedding outside a browser shell The same declaration also renders inside a host that is not a Mateu shell — an IDE webview, a mobile app, another product's page. Five things the host has to settle, and it is worth settling them explicitly rather than per host: | | | |---|---| | **Size and layout** | the host decides the viewport; the embedded UI must not assume a full page | | **Theming** | do **not** assume the host's design tokens are present. A component that reaches for `--lumo-*` renders unstyled in an IDE webview — use your own tokens with fallbacks | | **Authentication** | the host holds the session; the embedded UI has to be told, not discover it | | **URL and history** | decide who owns them. Inside a webview the embedded UI usually must **not** touch browser history | | **Events** | which events may escape to the host, and which stay inside | Mateu does not enforce these; they are the contract you agree with the host. Getting theming wrong is the one that bites first and looks like "the UI is broken" rather than "a variable is missing". --- # Why Mateu URL: https://mateu.io/mateu-about/why-mateu/ > The problem Mateu solves and what you gain from it. Most business applications accumulate complexity that has nothing to do with the domain. The problem starts the moment the team splits into a backend and a frontend. ## The accidental complexity problem A typical internal tool starts simple. Then the standard approach splits it: ```text domain model (Java) -> application layer (Java) -> REST API (Java, OpenAPI) -> API client (TypeScript) -> frontend model (TypeScript) -> frontend validation (TypeScript / Zod) -> UI state (React / Redux / Zustand) -> routing (React Router / Next.js) -> component library (MUI / Tailwind) ``` Every layer has to be built, kept in sync, and maintained. A change to a field in the domain model triggers a cascade through all of them. For a consumer product, that split is often worth it. For an order management screen, a role editor, or an internal control plane — it rarely is. ## What Mateu changes Mateu keeps the definition in one place: ```text one model (YAML · visual editor · Java · C# · Python) -> Mateu wire model -> any renderer: browser, phone, IntelliJ ``` The model defines what the UI is. The renderer decides how it looks. The deployment — a backend in any supported language, or a static bundle with none — decides where it runs. There is no separate frontend application to build, deploy, or maintain. The rest of this page uses the code path (Java) for its examples, because that is where most of the duplication it describes lives; the same arguments hold for a UI authored in YAML over existing APIs. ## Concrete benefits ### One model, not three In a traditional stack, an `Order` entity typically lives in three places: the backend domain model, the API response DTO, and the frontend TypeScript model. A field added to the domain model has to be propagated to the DTO and then to the TypeScript type. Miss one step and the UI silently shows stale data. With Mateu, the `Order` appears once. Adding a field to `OrderRow` adds it to the list. Adding it to `OrderEditor` adds it to the edit form. There is no propagation step. ### Fewer moving parts A Mateu project is either a backend (Java, .NET or Python) with a Mateu dependency and a renderer, or a folder of YAML files built into a static bundle. A traditional equivalent adds a REST API layer, a frontend project with its own build tool, package manager, component library, and state management, plus a separate CI/CD pipeline and deployment target. That operational difference compounds over time, especially where frontend expertise is limited or where the UI is not the primary product. ### Validation enforced once :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Bean Validation annotations on ViewModel fields are enforced in the browser (for user experience) and on the backend (for correctness). You write the constraint once. It applies in both places. No Zod schema. No frontend validation library. No risk of the frontend and backend disagreeing about what is valid. ```java @NotEmpty String name; @DecimalMin("0.01") BigDecimal price; ``` ### Integration lives on the server In a SPA — hand-written or interpreted from metadata, as in low-code page builders — the browser is the integration point: each page knows which APIs it calls, holds a token for each of them, and combines their responses client-side. The integration topology of the application lives in the browser. With Mateu the browser speaks exactly one protocol with exactly one endpoint. All the fan-out — calls to APIs, use cases, repositories, aggregating three services for one screen — happens on the server, in Java. That changes several things at once: - **Credentials never reach the browser.** Downstream APIs are called with server credentials; the client holds one session. No token-per-API in the browser, no CORS surface per origin. - **Contract breakage moves to compile time.** Screen-to-data wiring is typed Java calling typed use cases — it breaks in your CI, not at runtime in the user's browser. - **The fan-out runs on the datacenter network.** The client gets one round-trip with the composed result instead of a waterfall of API calls over the public internet. - **Governance in one place.** Auditing, caching, rate limiting and tracing apply where all the data access already flows — the server — instead of being scattered across pages. ### Stateless and horizontally scalable Mateu does not store UI state between requests. No sticky sessions, no session replication, no server affinity in Kubernetes. The ViewModel is created per request and discarded after the response. ### Pluggable renderers Mateu separates UI definition from rendering. The same ViewModel can be rendered by different design systems — Vaadin, Oracle Redwood — without rewriting any Java code. The definition is stable; the visual layer is pluggable. ### Architecture-friendly Mateu works alongside DDD and hexagonal architecture, CQRS with separate read and write models, microservices with federated UIs, and event-driven systems. The ViewModel calls the same use cases, query services, and ports that a REST controller would call. See [Mateu and system architecture](/mateu-about/system-architecture) for the full picture. ## Design principles **The model is the source of truth.** UI definitions live in your repository, next to the code or the APIs that power them — as classes or as YAML. There is no separate UI layer to keep in sync. **Stateless interaction.** Mateu does not store UI state on the server between requests. This keeps the system horizontally scalable and compatible with modern deployment infrastructure. **Adapters, not frameworks.** The UI is an inbound adapter — the same architectural concept as a REST controller. It calls the same application use cases, the same query services, the same ports. **Integration lives on the server.** The browser speaks one protocol with one endpoint; every call to APIs, services and repositories happens server-side. The client is a terminal, not an integration point. **The browser is untrusted.** The UI definition is also the write-authorization boundary: on every request, hydration drops incoming state for fields the definition hides or locks for that user (`@EyesOnly`, `@ReadOnlyUnless`). What a user cannot edit in the UI, a tampered request cannot write either. **Rendering is pluggable.** The UI definition is a protocol. Different renderers can consume the same definition and produce different visual results. Switching design systems does not require rewriting the definition. ## Who it is for Teams building internal tools, admin panels, distributed backoffices, and enterprise workflow applications — where the UI is a projection of the backend model, not the product itself. If your team is spending as much time on the frontend as on the domain logic for a tool that is ultimately CRUD-heavy, Mateu addresses that imbalance. ## What Mateu is not Mateu is not for marketing websites, highly animated UIs, or products where the UI is the primary value. For those, a traditional frontend framework is the right tool. ## Next - [How Mateu works](/mateu-about/how-mateu-works) — the mental model and building blocks - [Comparison with traditional stacks](/mateu-about/comparison) — side-by-side contrast - [Build a full backoffice in 10 minutes](/build-a-full-backoffice-in-10-minutes) — see it in practice --- # Native Renderers URL: https://mateu.io/native/ > Render any Mateu UI natively — inside IntelliJ on the desktop, or on iOS and Android — without a browser. Mateu's API is not limited to web browsers. Because the renderer is decoupled from the backend, any client that speaks HTTP and understands the Mateu component tree can render a Mateu application natively. Native renderers trade the browser's zero-install convenience for **better performance** and an OS-native feel — and, on the desktop, for a **docking/tabbed productivity workspace** the browser can't offer. (For when to prefer web vs. native, see [Web or native?](/design-systems/#web-or-native).) Two native renderers are available out of the box: - **[IntelliJ plugin](#desktop--intellij-plugin)** — desktop, rendered **inside IntelliJ IDEA** with the full IDE platform: tool windows, editor tabs, docking, Search Everywhere. - **[React Native](#mobile--react-native)** — iOS & Android, built with Expo/TypeScript. ## Desktop — IntelliJ plugin The IntelliJ plugin renders your Mateu backend **inside the IDE**, using the IntelliJ platform as the desktop shell. It targets power users who live in the IDE — internal tools, back-office operations, admin panels — and inherits, for free, the most battle-tested desktop workspace there is: dockable tool windows, split/floating editor tabs, keyboard-first navigation. **IDE-native UX** — the plugin does not imitate a web page; each Mateu concept maps to the IDE's own idiom: - The **app menu** appears as a widget on the IDE's **main toolbar** (like the Version Control widget) and as a navigator **tool window**; menu entries are also registered as IDE actions, so they show up in **Search Everywhere** (double Shift). - **CRUD listings** open in the **bottom tool window** (like Find/Search results) with a native search field (history included), column speed search, and **row context menus**; row actions and inline editing follow the listing's wire flags (row-form dialogs with ◀▶ prev/next navigation when inline editing is off). - **Details, forms and wizards** open as **editor tabs** — split them side by side, drag them out into floating windows, close them with the usual shortcuts. Tab titles track the view title; unsaved changes show the editor's **modified dot** and closing the tab asks before discarding (the standard `@ConfirmOnNavigationIfDirty` dirty guard, IDE-style). - **Toolbars** render on the editor header and the tool-window title bar; Mateu keyboard shortcuts (`@Action(shortcut=…)`) are registered as **IDE shortcuts**; backend messages use IntelliJ's **native notifications**. - A **focused mode** hides the IDE chrome that isn't yours (foreign tool windows, VCS/run widgets), leaving a clean business-app frame. **Run it:** ```bash cd frontend/app/intellij-plugin ./gradlew runIde # launches an IDE with the plugin installed ``` Then open a project, point it at your backend in **Settings | Tools | Mateu** (base URL or app registry, plus bearer-token or OpenID Connect sign-in — see [IDE tooling](/native/ide-tooling/)), or pass `-Dmateu.baseUrl=…` to `runIde`, and reveal the **Mateu** tool window. A project with no backend configured is left untouched. See `frontend/app/intellij-plugin/README.md` for platform overrides and the `renderProbe` verification harness (render the captured wire JSON to a Swing tree + PNG without booting the IDE). **Ship it as an installer** — one Gradle task bundles the plugin *with* the IDE: ```bash ./gradlew buildInstaller \ -Pmateu.registryUrl=https://registry.example.com -Pmateu.appId=demo-admin-panel ``` This produces a portable `mateu-desktop-<version>-linux.tar.gz` (or `-Pinstaller.platform=windows` for a `.zip`): IntelliJ IDEA Community with the Mateu plugin preinstalled, isolated `data/` config (it never interferes with an IDE the user already has), first-boot prompts pre-answered, and a `mateu.sh`/`mateu.bat` launcher that opens the bundled workspace directly — unpack and double-click. The optional registry properties bake the [app registry](#app-registry-pointing-installables-at-their-backend) coordinates into the launcher, which is how a production desktop installable gets its backend. **Source:** `frontend/app/intellij-plugin/` ## Mobile — React Native The React Native renderer runs your Mateu backend as a **native mobile application** on iOS and Android. It is built with [Expo](https://expo.dev) and TypeScript, and uses React Navigation for screen and drawer management. Pointing it at a backend, signing in to a secured backend (OIDC) and store builds have their own page: **[React Native renderer](/native/react-native/)**. **How it works:** 1. On startup, `App.tsx` resolves the backend (see the [app registry](#app-registry-pointing-installables-at-their-backend) below), calls `initialLoad('')` and receives the root component tree. 2. If the root component is of type `App`, `AppRenderer` builds the navigation structure — a Drawer for `NAVIGATION_LAYOUT`/`MENU_ON_LEFT` variants, a Bottom Tab navigator for `TABS`, or a simple Stack for `MEDIATOR`. 3. Each menu entry maps to a content screen that fetches its data on demand; detail navigations push screens onto a per-screen view stack with a back bar. 4. Pages, forms, CRUD tables, and individual fields are rendered as native React Native components (`TextInput`, `Switch`, `FlatList`, `TouchableOpacity`, etc.). 5. **Every** component type of the wire has a native rendering — dashboards (`DashboardLayout` mobile-first, KPI band on top), foldouts (overview card + accordion), Gantt, grids, menus, carousels, outcome pages, read-only BPMN/workflow diagrams… — with documented mobile adaptations (long-press instead of hover or right-click, multi-column layouts stacking on a phone). CI enforces it: see the [React Native component coverage](/reference/parity/#react-native-component-coverage). **Key files:** | File | Role | |---|---| | `App.tsx` | Entry point — registry boot gate, root load, toast/overlay/dirty-guard hosts | | `src/api/MateuApiClient.ts` | HTTP client — calls `POST /mateu/v3/sync/{route}` | | `src/core/AppRegistry.ts` | App registry client — installable → registry entry → backend config + version gate | | `src/core/MateuViewController.ts` | Pure-TS increment pipeline for ONE view — fragments, commands, action bubbling, client-side validation, dirty tracking | | `src/core/MateuSession.ts` | App-wide services — HTTP client, `appState`, event bus (`@SubscribeTo`), host hooks (toasts, overlays, confirm) | | `src/renderer/MateuViewHost.tsx` | Hosts one view controller and re-renders on every increment | | `src/renderer/AppRenderer.tsx` | Builds navigation structure from app metadata + the per-screen view stack | | `src/renderer/PageRenderer.tsx` | Renders pages with header, toolbar, children, and buttons | | `src/renderer/FormRenderer.tsx` | Renders forms with scrollable field list | | `src/renderer/FormFieldRenderer.tsx` | Renders individual fields (text, boolean, date, options, grids, capture fields…) | | `src/renderer/DateField.tsx` | Dependency-free calendar picker for `date`/`datetime` fields and date filters | | `src/renderer/CrudRenderer.tsx` | Renders tables with search, filters panel, pagination, and row navigation | | `src/renderer/ComponentRenderer.tsx` | Dispatcher — routes each component node to the right renderer | | `src/renderer/LayoutRenderer.tsx` | Renders horizontal and vertical layouts | | `src/renderer/DashboardRenderer.tsx` | Renders `MetricCard`, `Scoreboard`, `DashboardPanel`, `DashboardLayout` | | `src/renderer/DisplayRenderer.tsx` | Renders `FoldoutLayout`, `HeroSection`, `EmptyState`, `Skeleton`, `Gantt` and the other display components | | `src/renderer/WireComponents.tsx` | Grids, menus, breadcrumbs, avatars, messaging, layouts, outcome pages, elements, diagrams | | `src/core/auth.ts` / `oidc.ts` | Token provider (Bearer), built-in OIDC sign-in, 401 re-auth | | `src/api/metadata.ts` | TypeScript wire types for the dashboard/display component metadata | **Source:** `frontend/app/react-native/` ### App registry: pointing installables at their backend A native installable should not hardcode its backend URL — app-store releases are slow, and the same renderer binary often serves several environments. Instead, the installable carries only **two values**: a **registry URL** and an **app id**. A public registry maps the app id to everything else, so retargeting a backend, changing launch parameters, or forcing an upgrade is a registry edit — no republishing: ```json // GET {registryUrl}/{appId}.json (any static hosting works: S3, GitHub Pages, nginx…) // or {registryUrl} with an {appId} placeholder, for dynamic registries { "appId": "demo-admin-panel", "baseUrl": "https://apps.example.com/admin", "parameters": { "tenantId": "1111" }, "requiredRendererVersion": "1.2.0", "storeUrl": { "android": "https://play.google.com/store/apps/details?id=…", "ios": "https://apps.apple.com/app/id…" }, "intellij": { "requiredPluginVersion": "0.2.0", "requiredIdeBuild": "243.0", "downloadUrl": "https://plugins.example.com/mateu-latest.zip" } } ``` - **`baseUrl`** — the Mateu backend the renderer talks to from then on. - **`parameters`** — seeded into the `appState` sent with every request (the server reads them via `HttpRequest`, like `@AppContext` values). - **`requiredRendererVersion`** — minimum installable version able to run this app. When the installed renderer is older, the app shows a blocking **Update required** screen *before* touching the backend: it first tries an **over-the-air update** (real for EAS-built Expo installables via `expo-updates`; the app relaunches on the new bundle), and falls back to the platform **store link** (`storeUrl`) when no OTA update is available. A **Check again** button re-reads the registry, so lowering the requirement unblocks users without reinstalling. - **`intellij`** — desktop requirements: `requiredPluginVersion` (minimum Mateu plugin version) and `requiredIdeBuild` (minimum IntelliJ build number, e.g. `243.0` = 2024.3). Each renderer reads its own block and ignores the others'. - From there on, everything works as usual — the registry is only consulted at boot. **React Native wiring** (`src/core/AppRegistry.ts` + the boot gate in `App.tsx`): the registry coordinates live in the installable's `app.json` under `expo.extra` — ```json "extra": { "mateuRegistryUrl": "https://registry.example.com", "mateuAppId": "demo-admin-panel" } ``` — or, during development, in the `EXPO_PUBLIC_MATEU_REGISTRY_URL` / `EXPO_PUBLIC_MATEU_APP_ID` environment variables. With neither set, the renderer boots against its dev config (localhost / the Expo dev-server host). A ready-to-copy entry lives in `registry-example/demo-admin-panel.json`; to try the whole flow locally, serve that folder over HTTP (with CORS for web) and run: ```bash EXPO_PUBLIC_MATEU_REGISTRY_URL=http://localhost:8765 \ EXPO_PUBLIC_MATEU_APP_ID=demo-admin-panel \ npx expo start --web ``` **IntelliJ plugin wiring** (`plugin/AppRegistry.kt` + the boot gate in `MateuProjectService`): the coordinates live in the plugin's bundled `application.properties` (`mateu.registryUrl` + `mateu.appId`; system properties override them, e.g. `./gradlew runIde -Dmateu.registryUrl=…`). The gate resolves the entry off the EDT before the app boots; an unmet `intellij` requirement replaces the navigator with an **Update required** panel whose *Update now* button runs the IDE's own **Check for Updates** flow — the same one behind *Help ▸ Check for Updates*, which installs both plugin and platform updates — and opens the entry's `downloadUrl` when one is provided; *Check again* re-reads the registry. Registry errors show a Retry panel + an IDE notification. Headless verification: `./gradlew -q registryProbe` (entry URL resolution, fetch/parse against a throwaway local registry, version comparator, gate decisions). ### Building installables — APK, Play Store, App Store Packaging and store submission go through **EAS**, preconfigured in the module (`eas.json` + npm scripts; sign in once with `npx eas-cli login`): ```bash cd frontend/app/react-native npm run build:apk # .apk for sideloading / QA (or build:apk:local with an Android SDK) npm run build:android # .aab for the Play Store npm run build:ios # .ipa for the App Store npm run submit:android # upload to the Play Store (service-account JSON, internal track) npm run submit:ios # upload to App Store Connect (API key) ``` Set the installable's [app-registry](#app-registry-pointing-installables-at-their-backend) coordinates as variables of the profile's **EAS environment** (`npx eas-cli env:create`) — that is how a store build knows its registry; store credentials live in EAS too, never in the repository (details: [store builds](/native/react-native/#4-store-builds)). EAS also hosts the **over-the-air updates** the registry's version gate triggers (`expo-updates`; `runtimeVersion` is pinned to the app version so updates only reach compatible installables). ### Running and testing the mobile renderer All options assume a Mateu backend running locally (by default `http://localhost:8594`, the `demo-front-office` app — override with `EXPO_PUBLIC_MATEU_BACKEND_PORT`, e.g. `8595` for `demo-admin-panel`). From your IDE (IntelliJ included) the commands below run fine from the integrated terminal, or as an **npm Run Configuration** (Run → Edit Configurations → `+` → npm → pick the module's `package.json` and the `web`/`start` script) so launching the renderer is one click. **1. Browser with a phone viewport — fastest, zero install** ```bash cd frontend/app/react-native npm run web # expo start --web ``` Open the printed URL in Chrome and turn on device mode (`F12` → phone icon, or `Ctrl+Shift+M`), then pick a device preset ("iPhone 14", "Pixel 7"…). You get the mobile viewport, touch events, and hot reload as you edit the renderer code. It is not a real phone (no native camera, system gestures, etc.), but for iterating on UI it is very faithful. **2. Your real phone with Expo Go — the genuine experience, ~2 minutes** Install the free **Expo Go** app (App Store / Play Store), put the phone on the same Wi-Fi as your machine, and: ```bash cd frontend/app/react-native npm start # expo start — prints a QR code ``` Scan the QR with the camera (iOS) or from Expo Go (Android). The app opens on the phone with hot reload. The backend host is **derived automatically** from the Expo dev server the bundle was loaded from (`hostUri`), so as long as the backend runs on the same machine as `expo start`, no configuration is needed — just make sure your firewall allows ports **8081** (Metro) and your backend port (e.g. **8594**). If your network isolates Wi-Fi clients, `npx expo start --tunnel` routes around it (over the internet, slower). **3. Android emulator / iOS simulator** With Android Studio installed and an AVD created (Device Manager → any Pixel image), `npm run android` starts Expo and launches the app in the emulator. On macOS, `npm run ios` does the same with the iOS Simulator (requires Xcode). This is the heaviest option to set up, but gives you a full mobile OS in a window — useful for testing the real camera flow (Android emulator) or platform-specific behaviors. ## How the renderers relate to the Mateu API All native renderers implement the same protocol as the web renderers: ``` POST /mateu/v3/sync/{route} Body: { route, consumedRoute, actionId, serverSideType, initiatorComponentId, componentState, appState, parameters } ``` This means **the same Mateu backend serves web, desktop, and mobile clients simultaneously** with no code changes. You choose which renderer (or which combination) fits your deployment. ## Related - [Design systems](/design-systems/) — web renderers based on different component libraries - [Architecture](/mateu-about/architecture/) — how renderers connect to the Mateu API - [Bring your own design system](/design-systems/bring-your-own-design-system/) — build a custom renderer --- # IDE tooling: IntelliJ and VS Code URL: https://mateu.io/native/ide-tooling/ > Author Mateu YAML in your IDE: schema validation, the visual editor, New | Mateu file templates, and connecting a project to its backend with authentication. Both IDE integrations author the same `specs/ui/**` files and share their file skeletons, so a team can mix editors freely. | | IntelliJ plugin | VS Code extension | |---|---|---| | Schema validation + completion for `specs/ui/**` YAML | ✅ bundled specs schema | ✅ `yamlValidation` (needs the Red Hat YAML extension) | | Visual editor (palette, canvas, properties) | ✅ JCEF editor tab | ✅ custom editor | | Redwood canvas (the real Oracle VB renderer, editable) | ✅ served by the plugin | ✅ served by the extension | | New file from a template (mount, routes, app shell, sources, pages) | ✅ **New \| Mateu** | ✅ **Mateu: New File…** | | Add a route to a routes file (and set the mount's home) | ✅ **Add Mateu Route…** | ✅ **Mateu: Add Route…** | | Binding checks against the Java view model (+ quick fixes) | ✅ | — | | Runs the Mateu app inside the IDE | ✅ ([native renderer](/native/)) | — | | Per-project backend + authentication | ✅ Settings \| Tools \| Mateu | `mateu.baseUrl` setting | IntelliJ needs a **Java IDE** (IntelliJ IDEA Community or Ultimate): the binding checks resolve view models through the Java plugin. ## The visual editor's canvas: Vaadin or Redwood Both editors can paint the canvas with the **Vaadin** renderer or with the real **Redwood** renderer, which is the Oracle Visual Builder app of `io.mateu:mateu-redwood`. The canvas opens in the project's renderer (`project.yaml`, below), and the selector in the editor's toolbar previews the other renderer for the session. See [the Redwood canvas](/define/yaml/visual-editor/#the-redwood-canvas). In both IDEs the Redwood app is part of the editor's bundle. The IDE's local server serves it, so it works with no backend running. VS Code frames it from the extension's loopback server, because a webview cannot host the app itself. A bundle built without the Redwood app falls back to the configured backend's own (`/_index.html`, `/_redwood/`). In every case Redwood loads Oracle JET and the Visual Builder runtime from **Oracle's CDN**, so the IDE needs to reach `static.oracle.com`. Without it the canvas shows a notice instead of the page, and the Vaadin canvas keeps working offline. ## The project's renderer: project.yaml The renderer is a **project** setting, kept in `specs/ui/project.yaml` (`type: Project`, `renderer: vaadin | redwood`; see [project settings](/define/yaml/project-settings)). Both IDEs edit that file, and the file is the source of truth: - **IntelliJ**: **Settings | Tools | Mateu → Project → Renderer** reads `project.yaml` when the page opens and writes it on **Apply**. It creates the file if it is missing and rewrites only the `renderer:` line. - **VS Code**: the `mateu.renderer` setting follows the file. It is synced from the file on activation and whenever the file changes, and changing the setting writes the file. The command **Mateu: Project Settings…** asks for the renderer and writes the file too. - **New | Mateu → Project Settings** creates the descriptor. It is offered only while the project has none, because there is one per project. - The **UI Mount** wizard shows the project's renderer and the artifact the app must depend on (`io.mateu:mateu-vaadin` or `io.mateu:mateu-redwood`). The visual editor's canvas, Play and Export use this renderer. The canvas's own toolbar switch is only a preview for the session. ## Creating files: New | Mateu Right-click a folder in the Project view (or press ⌘N / Alt+Insert on it) and pick **New | Mateu**. In VS Code, right-click a folder in the Explorer and choose **Mateu: New File…** (also in the command palette). Every kind of file under `specs/ui` is offered: | Entry | Creates | Notes | |---|---|---| | **UI Mount** | `type: UI` | An app served at a base path — the data-driven `@UI`. Lists its route files. Optionally names its **home page route** (`home:`, the page the mount opens on — see [the mount's home](/concepts/routes-and-mounts/#the-mounts-home)) — usually left empty at creation and set later from Add Route…. | | **Routes File** | `type: Routes` | Created **empty** (`routes: []` under a short header pointing at [the route registry](/concepts/routes-and-mounts/)). Pick the **mount** (`type: UI`) to register it in — it is appended to that mount's `routes:` list (preselected when there is exactly one). The optional **base path** is only for a class-declared `@UI("/shop")` mount. Add the entries one at a time with **Add Route…** (below). | | **App Shell** | `type: AppShell` | Title, variant, home route and a menu with a group. Bind it to the mount root (`""`). | | **Action Catalogue** | `type: Actions` | Created **empty** (`actions: []` under a short header). Named flows and REST calls the shell menu and any page run by id — see [the action catalogue](/concepts/action-catalogue/). The visual editor opens it in a structured editor (add / rename / describe / remove actions, edit their steps), and every action-id picker offers its ids marked **catalog**. | | **REST Source Catalogue** | `type: Sources` | Two example sources (`source:` nested, `provenance`, `fields`, `totalPath`). See [the REST source catalogue](/concepts/data-sources/). | | **Page…** | a page definition | Pick a **template** and a **page width** (below). When the folder has a routes file, **Add a route to `<routes file>`** (on by default) appends a route to the new page, named after the file — optionally making it the home page. | Page templates follow the [page templates](/ux-patterns/page-templates/) Mateu ships: | Template | Root | Default width | |---|---|---| | Form | `Form` with a `FormLayout` and Save / Cancel | fixed | | Listing / CRUD | `Listing` over a named source, filters, New, `rowRoute` to the record | full width | | Wizard step | `Form` with progress and Back / Next | fixed | | Dashboard | `Scoreboard` of `MetricCard`s over a `DashboardLayout` | full width | | Smart Search | intro line + searchable `Listing` with filters | full width | | To-do List | `TaskQueue` of counted buckets | fixed | | Calendar | toolbar + `Calendar` (month/week/day/list) | full width | | Welcome | `HeroSection` with calls to action + tiles | fixed | | Hero Search | `HeroSection` + `Listing` as cards | fixed | | Collection Detail | item list left, detail (empty state) right | full width | | General Overview | record switcher + `EntityHeader` + cards | full width | | Item Overview | sticky key-info card + `TabLayout` | full width | | Foldout | `FoldoutLayout` with panels | edge to edge | | Gantt Page | title + `Gantt` | edge to edge | | Data Management | grid ⇄ Gantt tabs | full width | | Matrix Grid | `MatrixGrid` with sections, editable row | edge to edge | | Planning Board | `PlanningBoard` resources × days | edge to edge | | Blank layout | an empty `VerticalLayout` | renderer decides | The **page width** (fixed = centred, max 1408px · full width = the whole content width · edge to edge = no margins) is written as the root layout's `style`, because a YAML definition has no `pageWidth` key; choose *Let the renderer decide* to leave it out. The style never adds a side gutter: the view the page renders in already has one (the app shell's, or the design system's when the page stands alone). **Where the file goes.** If you right-clicked a folder inside `specs/ui`, the file goes there. Otherwise the nearest existing `specs/ui` (`src/main/resources/specs/ui` or `specs/ui`) at or above that folder is used; failing that, `src/main/resources/specs/ui` is created when the folder is a Maven/Gradle module, else `<folder>/specs/ui`. Existing files are never overwritten. Every skeleton is validated against the generated specs schema in the plugin's test suite (strictly: a key the schema does not declare fails), so a new file never starts out red. Both editors validate against the same generated schema (`backend/shared/uidl/specs-schema.json`), in two spellings: IntelliJ reads it as generated, while the VS Code extension stages a variant whose polymorphic families (`Component`, `Actionable`, …) are rewritten as `type` dispatches — the shape the Red Hat YAML language server validates in milliseconds instead of trying all 125 component branches at every level on every keystroke. Same files accepted, same files refused; one source. In IntelliJ the skeletons are ordinary file templates — customise them in **Settings | Editor | File and Code Templates | Other** (`Mateu …` entries). Placeholders: `__TITLE__`, `__NAME__`, and a line holding only `__PAGE_WIDTH__`. ## Adding routes: Add Route… A route registry grows **one entry at a time**. In IntelliJ, right-click a `type: Routes` file in the Project view or inside its editor and choose **Add Mateu Route…** (also under **New | Mateu › Route…** when the folder has a routes file). In VS Code, run **Mateu: Add Route…** from the Explorer or editor context menu of the routes file, or from the command palette. You choose: | Field | Written as | Notes | |---|---|---| | Routes file | — | Preselected when invoked on one; a choice when the specs folder has several. | | Layout | `layout:` | A page or app shell discovered under `specs/ui` (relative to it), or none when the view model supplies its own tree. `layout` is the canonical key (`definition` is its deprecated alias). | | Route | `route:` | Relative to the mount; empty is the mount root (typically the app shell). Defaults to the layout's file name in kebab case. A route already declared in the file is rejected. | | View model | `viewModel:` | Optional fully qualified class — empty is a definition-only route, which is valid (the statically served case). | | Parent route | `parent:` | Optional: one of the file's existing routes; the new route renders in that screen's slot (the route stays absolute). | | Make this the home page | `home:` in the mount | Sets (or replaces) the `home:` route of the `type: UI` mount that lists this routes file, and shows the current one. Disabled when no mount lists the file. | Every change is a **minimal text edit**: the entry is appended after the last one (the first one turns `routes: []` into a block list), the mount gets one new line, and nothing else in your files is reformatted. Fixed/default parameters, `children` and the data scopes are then edited by hand — see [the route registry](/concepts/routes-and-mounts/). ## Connecting IntelliJ to a backend: Settings | Tools | Mateu The plugin stays out of projects that are not Mateu apps: with no backend configured it makes no HTTP calls, shows no Mateu tool windows or toolbar widget, and never touches the window title. Configure a project in **Settings | Tools | Mateu** (stored in `.idea/mateu.xml`): - **Base URL** of the backend (e.g. `http://localhost:8080`) and the **start route**; or an **app registry URL + app id**, which resolves the base URL and launch parameters. - **Authentication**: - *Bearer token* — pasted once, kept in the IDE credential store (Keychain, KWallet, KeePass…), never in the project; sent as `Authorization: Bearer` on every Mateu call. - *OpenID Connect (device sign-in)* — issuer + client id (endpoints are discovered, or set explicitly). **Sign In…** shows a code and opens your browser; the refresh token is kept in the credential store and access tokens are refreshed silently. - A **401** first tries a silent refresh; otherwise one notification offers **Sign in…** / **Open settings**, and the request is retried once with the new credentials. JVM system properties override the settings, for CI or a one-off run: `-Dmateu.baseUrl`, `-Dmateu.route`, `-Dmateu.registryUrl`, `-Dmateu.appId`, `-Dmateu.token`; `-Dmateu.debug=true` logs the wire traffic. The standalone desktop distribution (the IDE rebranded as your app, see [Desktop & Mobile](/native/)) is the only place the plugin takes over the frame title, hides foreign tool windows and lands on the home route. ## Live development: Run Mateu App (Live) **Run | Run Mateu App (Live)** (also under **Tools**) starts the project's app in development mode (`mateu.dev=true`, every `src/main/resources/specs/ui` of the project watched) with the debug agent listening, attaches a *Remote JVM Debug* session once it answers, points **Settings | Tools | Mateu** at it when nothing else is configured — so this tool window and the **visual editor's Play** use the running app — and opens it in the browser. From then on a YAML edit (in the text editor or the visual editor's canvas) re-renders the open screen in place, and every **HotSwap** fires `POST /mateu/dev/reload` so the screen shows the new code. **Run | Reload Mateu Screen** fires it by hand. Spring Boot, Quarkus, Micronaut and Helidon apps (Maven or Gradle) are detected. VS Code has the same pair: **Mateu: Run App (Live)** and **Mateu: Reload Screen** (also fired on a Java hot code replace). Details, adapters and limits: [Live reload](/java-user-manual/build/live-reload/). --- # React Native renderer (iOS & Android) URL: https://mateu.io/native/react-native/ > Run any Mateu backend as a native mobile app: pointing it at a backend, the app registry, sign-in against a secured backend, and store builds. The React Native renderer (`frontend/app/react-native`, Expo SDK 57 / React Native 0.86, TypeScript) turns any Mateu backend into a **native iOS and Android app**. It speaks the same `POST /mateu/v3/sync/{route}` wire as the web renderers, so the backend needs no changes — one server serves web, desktop and mobile at once. It is a **fully supported** renderer: every component type of the wire has a native rendering (see the [coverage table](/reference/parity/#react-native-component-coverage)), and CI fails the build if a new wire type arrives without one. For the architecture and the other native renderer see [Desktop & Mobile](/native/). ## 1. Point it at a backend Three ways, from quickest to production: | Situation | How the app finds its backend | |---|---| | Local development (`npm run web`, Expo Go, emulator) | `http://<dev host>:8594` — the host is the Expo dev server's (`hostUri`, so a phone on your Wi-Fi reaches your laptop), the port is `EXPO_PUBLIC_MATEU_BACKEND_PORT` (default **8594**, `demo/demo-front-office`) | | Any build pointing at a fixed backend | `EXPO_PUBLIC_MATEU_REGISTRY_URL` + `EXPO_PUBLIC_MATEU_APP_ID` → the [app registry](#2-the-app-registry) | | Store installables | the same two values, set in the EAS environment of the build profile (see [store builds](#4-store-builds)) | ```bash cd frontend/app/react-native npm ci EXPO_PUBLIC_MATEU_BACKEND_PORT=8595 npm run web # demo-admin-panel on :8595, in a browser npm start # QR code for Expo Go on a real phone ``` `EXPO_PUBLIC_MATEU_ROUTE=/some/route` boots straight into a route instead of the home screen; in the browser build, `?route=/some/route` on the page URL does the same without a rebuild. **In a browser (`npm run web`) the backend must allow the Expo origin.** The page is served from another origin than the backend, and Mateu's CORS is off by default — without this the app stops at *"Can't reach the server"* and the browser console shows a CORS error: ```bash java -jar target/demo-admin-panel-0.0.1-SNAPSHOT.jar --mateu.cors.allowed-origins=http://localhost:8081 ``` Expo Go, simulators and installables are not browsers: they need no CORS setting. ## 2. The app registry An installable carries only a **registry URL** and an **app id**. At boot it fetches `{registryUrl}/{appId}.json` (or the URL with `{appId}` substituted) and gets everything else, so retargeting a backend, changing launch parameters, forcing an upgrade or switching the identity provider is a registry edit — not a store release: ```json { "appId": "front-office", "baseUrl": "https://apps.example.com/front-office", "parameters": { "tenantId": "1111" }, "requiredRendererVersion": "1.0.0", "storeUrl": { "android": "https://play.google.com/…", "ios": "https://apps.apple.com/…" }, "auth": { "type": "oidc", "issuer": "https://login.example.com/realms/acme", "clientId": "mateu-mobile", "scopes": ["openid", "profile", "email", "offline_access"] } } ``` - `parameters` are seeded into the `appState` of every request. - `requiredRendererVersion` gates the boot: an older installable shows **Update required**, tries an over-the-air update (EAS Update) and falls back to `storeUrl`. - `auth` turns sign-in on — next section. ## 3. Signing in to a secured backend A secured Mateu backend resolves identity (`@EyesOnly`, `@ReadOnlyUnless`, `@DisabledUnless`, `HttpRequest` roles) from a JWT sent as `Authorization: Bearer <token>`. The native renderer sends it on **every** Mateu request (and on the AI chat), from a pluggable **token provider**: - **Built-in OIDC** — declare `auth` in the registry entry (or, in dev, `EXPO_PUBLIC_MATEU_OIDC_ISSUER` / `_CLIENT_ID` / `_SCOPES` / `_AUDIENCE`). The app runs the Authorization Code flow with **PKCE** in the system browser (`expo-auth-session`), keeps the tokens in the **keychain / keystore** (`expo-secure-store`; `localStorage` on web), refreshes the access token before it expires, and shows a **Sign in** screen before the first screen (`"loginOnStart": false` signs in only when a request comes back 401). A **Sign out** entry appears at the bottom of the drawer. Works with any standards-compliant provider (Keycloak, Entra ID, Auth0 — add `"audience"` —, Okta, Cognito…): it only needs the issuer's discovery document. - **Your own login** — register any provider: `setTokenProvider({ getToken, refresh, login, logout })` from `src/core/auth.ts`. Register these redirect URIs as allowed for the client at the identity provider: `mateu://auth` (iOS/Android — the app's scheme is `mateu`) and `<web origin>/auth` (expo web). **Session expiry** follows the web renderers' contract: a **401** gives the app one chance to re-authenticate — an explicit `onSessionExpired(handler)` (`src/core/sessionGuard.ts`) wins; otherwise the provider refreshes silently, then prompts — and the original request is retried **once**, so a half-filled form survives. Concurrent 401s share a single re-authentication. Every installation also sends its own `X-Session-Id` (a random UUID created on first launch and kept in secure storage), so two devices never share a server-side session. ## 4. Store builds Builds go through [EAS](https://docs.expo.dev/build/introduction/) (`npx eas-cli login` once). `eas.json` has three profiles; each maps to an **EAS environment** and an **EAS Update channel** of the same name: | Profile | Use | Network | App id | |---|---|---|---| | `development` | internal APK against a LAN backend | cleartext `http` allowed (Android `usesCleartextTraffic`, iOS local networking) | `io.mateu.app.dev` | | `preview` | internal APK / ad-hoc for QA | **https only** | `io.mateu.app` | | `production` | Play Store `.aab` / App Store `.ipa` | **https only** | `io.mateu.app` | ```bash # registry coordinates per environment — nothing environment-specific is committed npx eas-cli env:create --environment preview --name EXPO_PUBLIC_MATEU_REGISTRY_URL --value https://registry.example.com npx eas-cli env:create --environment preview --name EXPO_PUBLIC_MATEU_APP_ID --value front-office npm run build:apk # preview APK npm run build:android # production .aab npm run build:ios # production .ipa npm run submit:android # Play Store, internal track npm run submit:ios # App Store Connect ``` **Store credentials are never in the repository.** Upload them once to EAS (`npx eas-cli credentials`: the Play service-account JSON and the App Store Connect API key), or provide them on the submitting machine (`EXPO_ASC_API_KEY_PATH`, `EXPO_ASC_KEY_ID`, `EXPO_ASC_ISSUER_ID`). **Over-the-air updates**: `npx eas-cli update --channel production` publishes a new JS bundle to production installables; `runtimeVersion` follows the app version, so an update only reaches binaries it is compatible with. The camera permission is the only runtime permission requested (for `@PhotoCapture`); the microphone is explicitly not. ## 5. Compatibility The app declares the oldest wire it supports (`MIN_WIRE_VERSION = "3.0"`, `src/core/wireVersion.ts`). Every response carries `wireVersion`: a server speaking another major version (or an older minor) gets a one-time **Version mismatch** warning instead of screens that silently render wrong; a newer minor is fine (the wire is additive within a major). ## 6. Checks ```bash npm test # unit tests (node --test) npm run typecheck # tsc --noEmit npm run parity # every wire component type has a native renderer; parity.md in sync node scripts/wire-fixture-server.mjs 18600 # a page of rarely-used component types, for eyeballing ``` Request and response bodies are logged to the console **only in development builds** (`__DEV__`). --- # Quality URL: https://mateu.io/quality/ > How Mateu's generated UX is evaluated, what it guarantees for accessibility, and how renderers and servers are held to the same output. Because every screen is derived from a model, quality is decided in one place — the derivation and the renderers — and every app gets it without code of its own. These pages describe how that quality is measured and enforced. ## UX - [How UX is evaluated](/ux-patterns/how-ux-is-evaluated/) — heuristic reviews, task walkthroughs, synthetic users, task metrics, and what each method catches and misses. - [UX patterns](/ux-patterns/) — the patterns screens are built from, each with its rationale. ## Accessibility - [Accessibility](/ux-patterns/accessibility/) — what is guaranteed for keyboard and screen-reader users on every renderer (web, Redwood, mobile, IntelliJ), and the probes that verify it. - [Accessibility in your code](/java-user-manual/advanced/accessibility/) — what is still yours to get right. ## Consistency across servers and renderers - [Wire specification](/reference/wire-specification/) — the single contract. - [Feature parity matrix](/reference/parity/) — what each server and each renderer supports. - [Renderer contract](/design-systems/renderer-contract/) — conformance levels for a renderer. - The repository's `conformance/` corpus renders the same cases in Java, .NET and Python and requires the outputs to match exactly. ## Testing and coverage - [Testing your UI](/java-user-manual/advanced/testing/) — testing view models in-JVM and end to end. - The project itself runs line-coverage gates on the Java core and on the web libraries, end-to-end Playwright suites against every Java adapter, and accessibility and slow-network probes against the renderers on every change. --- # The Mateu Way URL: https://mateu.io/the-mateu-way/ > The golden path: every screen is one of six things. Pick the family, start from its archetype, refine only where you disagree. Mateu has a large vocabulary — dozens of annotations, twenty-plus archetypes, some eighty UX patterns. **You do not need to know it.** That vocabulary is a reference library, not a syllabus. **Building a UI starts before any code: list the screens.** Take the app you have in mind and write down the screens it needs — "a products listing, a product detail, a check-in wizard, an operations dashboard". That screen map is the design. Then, screen by screen, it's three moves: 1. **Pick the family.** Every screen is one of six things (a business question, not a framework one). 2. **Start from the family's archetype.** One class, nearly empty, gives you a working screen. 3. **Refine only where you disagree.** Explicit always wins; below the template, layout inference fills the gaps you leave (columns, sections, widgets — see [layout inference](/ux-patterns/layout-inference/)). Choosing the template is a decision **you** make per screen — that's the normal path, not a fallback. Mateu can compose the template itself only for two fully-derivable shapes (a class of `MetricCard` fields → Dashboard, a class of `Button` CTAs → Welcome); for everything else it can at most hint (the advisor logs "this looks like a CollectionDetail"), and you pick. If you remember nothing else: *first the screen map, then start at the top of the ladder, descend only on disagreement.* ## Every screen is one of six things Mateu classifies every page into the six template families of the Redwood taxonomy — it even stamps the family on the wire (`pageType`) so renderers can adapt. The same six families are your entry point as a developer: | Family | The user is… | Start from | |---|---|---| | **Collection** | finding things in a set — searching, listing, opening, editing | `AutoCrud<T>` | | **Detail** | looking at *one* thing in depth | `ItemOverview` | | **Form** | completing one task: some fields, one action | a plain `@UI` class | | **Process** | moving through steps toward a result | `Wizard` | | **Dashboard** | monitoring numbers to decide what needs attention | `Dashboard` | | **Landing** | arriving — orientation and ways in | `Welcome` | To pick, ask at most three questions, in order: 1. **Many records or one?** Many → *Collection*. One → *Detail*. 2. **Is the user changing something?** In one shot → *Form*. Across steps → *Process*. 3. **Neither?** Watching numbers → *Dashboard*. It's the front door → *Landing*. ## The six starting points Each family has one blessed starting class. All of them work with an almost empty body — that is the point: the first version of every screen should be minutes, not days. ### Collection — `AutoCrud<T>` :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @UI("/products") public class Products extends AutoCrud<Product> { @Override public CrudStore<Product> store() { return new ProductStore(); // your CrudStore<Product> } } ``` Searchable listing with smart-search filters, detail view, edit and creation forms, validation, URL pagination. When the collection is not a plain table of editable records — a work queue, a calendar, cards with a detail pane — the family has sibling archetypes (`TodoList`, `CalendarPage`, `CollectionDetail`, `SmartSearchPage`); the [decision guide](/ux-patterns/choosing-a-page-template/) picks among them in one table lookup. ### Detail — `ItemOverview` ```java @UI("/products/360") public class ProductOverview extends ItemOverview { // first component field → sticky key-info panel (left) // @Panel("…") fields → tabs (right) } ``` Siblings for other detail shapes: `GeneralOverview` (record switcher on top), `Foldout` (lateral fold-out panels), or a read-only `Drawer` when the detail should not leave the page. ### Form — a plain `@UI` class ```java @UI("/feedback") @AutoLayout public class Feedback { @NotEmpty String subject; @Stereotype(FieldStereotype.textarea) String details; @Button Message send() { // call your use case return new Message("Thanks!"); } } ``` Fields become inputs, Bean Validation runs in the browser and on the server, `@AutoLayout` picks the presentation (folds optionals away, radios for small enums…). ### Process — `Wizard` ```java @UI("/onboarding") public class Onboarding extends Wizard { IdentityStep identity; // fields of each step class = the step's form PlanStep plan; // penultimate step shows the @WizardCompletionAction ResultStep result; // read-only result screen } ``` Branching (`stepApplies`), progress styles (bar, steps, rail) and cross-step state are built in. ### Dashboard — `Dashboard` ```java @UI("/ops") public class OpsDashboard extends Dashboard { // consecutive MetricCard fields → KPI band // @Panel("…") component fields → titled tiles on a responsive grid } ``` ### Landing — `Welcome` ```java @UI("") public class Home extends Welcome { // Button fields → CTAs in the hero // @Panel("…") components → highlight tiles below } ``` ## The ladder of control The archetypes are not a cage — they are the top rung of a ladder. Each rung down trades convention for control, **per screen**: one screen can live on rung 1 while the screen next to it is hand-built on rung 3. | Rung | You write | Use when | |---|---|---| | **1 — Archetype + inference** | a nearly-empty class; `@AutoLayout` decides presentation | the default. Start every screen here. | | **2 — Explicit annotations** | `@Section`, `@Zones`, `@Tab`, `@Toc`, `@PageWidth`, `@Compact`… | you disagree with an inferred decision. Explicit always wins; inference steps aside. | | **3 — Fluent components** | a component tree (`ComponentTreeSupplier`) | the screen's structure is yours, not derivable from a model. | | **4 — `ComponentAdapter`** | a renderer for an arbitrary domain object | the object cannot carry Mateu annotations at all. | When even that is not enough — the whole screen is none of the six families — there is a page-level escape too, with its own guarantees: see [When a screen does not fit](/java-user-manual/advanced/escaping-the-framework/). Two properties make the ladder safe to rely on: - **Descending is local.** Overriding one section's layout does not eject you from the archetype; rung 2 refinements live *inside* rung 1 screens. - **You can always climb back.** Delete the explicit annotation and inference resumes. Nothing is generated, so nothing goes stale. Mateu also nudges you toward the right rung: a plain form class that structurally resembles an archetype — `MetricCard` fields that would make a `Dashboard`, a selectable list next to a detail pane that would make a `CollectionDetail` — logs a one-time hint naming the archetype. Advice only, never a behavior change; `@PageTemplate` on the class silences it. And under [`@AutoPage`](/ux-patterns/layout-inference/#page-level-inference-autopage) the fully-derivable shapes go one step further and *compose* the archetype for you — declare the metrics, get the dashboard. ## The catalog is a library, not a syllabus The [UX patterns catalog](/ux-patterns/) documents everything Mateu can express — smart search, drawers, kanban, Gantt, optimistic locking, guided import… **Consult it; do not read it.** The moment you need "a side panel that doesn't lose the page" or "totals under a grid", the pattern page tells you the one annotation or archetype that does it. Until that moment, the six starting points above are the whole framework. The same applies to AI assistants: point them at the [AI assistant reference](/ai-assistant-reference/) and ask for the screen in business terms — the assistant's job is exactly the three moves of this page: family, archetype, refinements. ## Escape hatches — explicit, and relegated When the path does not fit, Mateu has deliberate exits. They are worth knowing *because* they are the exception — reach for them only when the rungs above genuinely do not cover the screen: - **Reuse a bound composition** → a [business component](/java-ui-definition/component-catalogue/): a named `dropdown + source` (etc.) referenced by name. Still the model — it ports for free and runs with no backend. This is reuse, not an escape; try it first. - **A rendering the catalog does not have** → a [custom component](/java-ui-definition/custom-components/): a genuinely new drawing, carried as data (`CustomComponent`) and rendered per-renderer. It does **not** port for free (each renderer registers it), which is exactly why it is the last resort — an un-taught renderer shows a visible placeholder, never a broken screen. - **Something no template covers** → drop to a hand-built component tree. What you keep on the way down (state, actions, validation, routing, the surrounding chrome) is pinned by a test. The rule across all three: an escape hatch is explicit in the model and visible on screen, so the golden path stays *seen* without the exceptions adding noise to it. ## Next - [The UX guide](/ux/) — the structure of an app, the [page types](/ux/page-types/) in YAML and code, and the components - [Choosing a page template](/ux-patterns/choosing-a-page-template/) — the fine-grained decision guide, family by family - [Quickstart](/java-user-manual/start-here/quickstart/) — a running app in minutes - [How Mateu works](/mateu-about/how-mateu-works/) — the mental model underneath --- # Use cases URL: https://mateu.io/use-cases/ Mateu is especially powerful for a specific type of applications. If you're building any of the following, Mateu can dramatically reduce complexity — whether you author the model in code (Java, C#, Python) or in YAML, and whether you serve it from a backend or ship it as a static bundle. --- ## Internal tools Build admin panels, dashboards, and back-office tools without a frontend team. ### Typical features - forms - tables - filters - actions - workflows ### Why Mateu fits - no frontend duplication - fast iteration - simple architecture --- ## CRUD applications Mateu shines in data-heavy applications. ### Example :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @UI("") public class Users { List<User> users = userService.findAll(); @Button Runnable create = () -> {}; } ``` Mateu generates: - tables - forms - actions --- ## Enterprise apps Large business applications often suffer from: - duplicated models - frontend/backend sync issues - complex architectures Mateu simplifies this by: - defining UI in one place - removing API glue - reducing moving parts --- ## Microservice UIs Mateu is stateless and works naturally with distributed systems. You can: - expose UIs from multiple services - compose them in a single frontend - scale independently --- ## Embedded UIs Mateu UIs can be embedded anywhere as web components. Use cases: - integrate into existing apps - expose specific forms - build modular UIs --- ## When NOT to use Mateu Mateu is not ideal for: - highly custom visual experiences - marketing websites - animation-heavy UIs --- ## Summary Mateu works best when: - UI is driven by data and actions - speed matters more than pixel-perfect design - you want fewer moving parts --- 👉 Try the live demo: https://vaadin.mateu.io/fluent/use-cases/rra --- # The UX guide URL: https://mateu.io/ux/ > How a Mateu UI looks and behaves, top-down: the structure of an app, the six page types, the component catalogue, how to extend it, and how UX quality is kept. The entry point to every UX page. import { Card, CardGrid } from '@astrojs/starlight/components'; You declare a Mateu UI **once**, without naming a design system: as YAML (by hand or in the [visual editor](/define/yaml/visual-editor/)) or as code in Java, C# or Python. Mateu renders that one declaration on the web with [Vaadin](/design-systems/vaadin/) or [Redwood](/design-systems/oracle-redwood/), on phones with the [Mateu app](/native/react-native/) and on the desktop in [IntelliJ](/native/), whether a backend serves it or it ships as a [static bundle](/deploy/static-bundle/). So "the UX" of a Mateu app is not something each screen invents. It is a **grammar** that every screen follows and every renderer paints. This guide explains that grammar from the outside in. [What a Mateu UI is made of](/concepts/building-blocks/) maps the *building blocks* (mount, routes, pages, actions, sources…); this guide is what those blocks look like to the person using the app. ## The grammar in one picture ```mermaid flowchart TD Mount["Mount<br/>an app at a base path"] --> Shell["App shell<br/>variant · header · menu"] Shell --> Header["App header<br/>context pickers · header actions · bell · search · theme"] Shell --> Nav["Navigation<br/>menu · card menus · remote menus · command center"] Shell --> Content["Content area<br/>the current route's page"] Content --> Page["Page<br/>one of six page types"] Page --> PHeader["Page header<br/>overline · title · badges · KPIs · toolbar"] Page --> Banners["Banners"] Page --> Body["Body<br/>components: layouts, fields, listings, displays"] Page --> Footer["Footer buttons · FABs"] Page -. "opens" .-> Overlays["Overlays<br/>dialogs · drawers · popovers · toasts"] ``` ## Read it top-down <CardGrid> <Card title="1. Structure of an app" icon="laptop"> The shell and its variants, the app header, navigation and menus, the content area, overlays, and the anatomy every page shares (header, banners, body, footer, FABs). [Structure of an app →](/ux/app-structure/) </Card> <Card title="2. Page types" icon="document"> Every page is one of six types: **collection**, **detail**, **form**, **process**, **dashboard** or **landing**. Each type, its templates, its anatomy and a minimal example. [Page types →](/ux/page-types/) </Card> <Card title="3. Components" icon="puzzle"> The catalogue, by role: layouts, fields, displays, collections, navigation, feedback, overlays and specialised canvases, plus field types and how renderers map them. [Components →](/ux/components/) </Card> <Card title="4. Extending it" icon="setting"> A ladder from least to most effort: semantic annotations, field types, custom components, adapters, micro-frontends, design systems and your own renderer. [Extending the UI →](/ux/extending/) </Card> <Card title="5. How quality is kept" icon="approve-check"> The principles, how they are checked, accessibility on every renderer, and behaviour on slow networks. [UX quality →](/ux/quality/) </Card> </CardGrid> ## Three ideas behind every page **The model says *what*, the renderer says *how*.** A page declares that it has a title, a listing with a status column and a primary *New* button. It never says "a `vaadin-grid`" or "an `oj-table`". That is why the same declaration looks native in Vaadin, Redwood, React Native and IntelliJ, and why a renderer cannot add UI the model did not ask for (see [the authoring rule](/authoring-rule/)). **You choose the page type, Mateu fills in below it.** Listing the screens your app needs and picking a type for each is the design step, and it is yours. Below that choice, Mateu infers a lot: widgets from field types, columns and sections from the amount of data, tabs for long read-only records ([layout inference](/ux-patterns/layout-inference/)). Explicit declarations always win over inference. **Patterns are a library, not a syllabus.** The [pattern catalogue](/ux-patterns/) documents more than ninety patterns (smart search, drawers, kanban, Gantt, undo, optimistic locking…). You do not need to read it. When you need "totals under a grid" or "a side panel that doesn't lose the page", the pattern page names the one annotation, key or archetype that does it. ## The same page, two renderers The same form, declared once, painted by the Vaadin renderer and by the Redwood renderer: ![A basic form rendered by the Vaadin renderer](/images/docs/design-systems/basic-form-vaadin.png) ![The same form rendered by the Redwood renderer](/images/docs/design-systems/basic-form-redwood.png) ## Where to go from here - **Designing a new app**: list your screens, then read [page types](/ux/page-types/) and run each screen through [choosing a page template](/ux-patterns/choosing-a-page-template/). - **Looking for one specific behaviour**: the [pattern catalogue](/ux-patterns/), grouped by role in the sidebar. - **Building it**: [The Mateu Way](/the-mateu-way/) for code, [pages in YAML](/define/yaml/pages/) for data. --- # Structure of an app URL: https://mateu.io/ux/app-structure/ > What a Mateu app looks like from the outside in: the mount, the app shell and its variants, the app header, navigation and menus, the content area, overlays, and the anatomy every page shares. import { Tabs, TabItem } from '@astrojs/starlight/components'; Every Mateu app has the same nested structure. Knowing it tells you where any piece of UI lives, which declaration controls it, and why it looks consistent on every renderer. ```mermaid flowchart TD Mount["Mount (type: UI · @UI)"] --> Shell["App shell (type: AppShell · @App)"] Shell --> AH["App header"] Shell --> Nav["Navigation (menu)"] Shell --> CA["Content area"] Shell --> AF["App-level floating buttons<br/>AI chat · command center · app FABs"] CA --> Page["Page"] Page --> PH["Page header"] Page --> PB["Banners"] Page --> Body["Body"] Page --> PF["Footer buttons"] Page --> FAB["Page FABs"] Page -.-> OV["Overlays: dialog · drawer · popover · toast"] ``` ## The anatomy, labelled This is the canonical arrangement on a wide web viewport with the menu on top. Other variants move the navigation (see [shell variants](#the-app-shell-and-its-variants)), and the native renderers adapt it to their platform (a drawer on a phone, tool windows in IntelliJ), but the parts are the same. ```text ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ [1] Logo · Title [2] Products Orders ▾ Reports [3] Hotel ▾ Actions ▾ 🔔 ☾ │ ← app header ├──────────────────────────────────────────────────────────────────────────────────────┤ │ [4] Home › Orders │ │ [5] SALES [9] ‹ › [10] Edit Export … │ │ [6] Order SO-1042 [7] Open Priority │ ← page header │ Placed by ACME Corp · Last updated 2 min ago [8] Total 1,240 € Lines 12 │ ├──────────────────────────────────────────────────────────────────────────────────────┤ │ [11] ⚠ Payment pending: the customer has not paid the deposit yet. ✕ │ ← banners ├──────────────────────────────────────────────────────────────────────────────────────┤ │ [12] ┌ Customer ───────────────┐ ┌ Shipping ────────────────┐ │ │ │ Name ACME Corp │ │ Address … │ │ ← body │ └─────────────────────────┘ └──────────────────────────┘ │ │ ┌ Lines ───────────────────────────────────────────────┐ │ │ │ Product Qty Price │ │ │ └──────────────────────────────────────────────────────┘ │ ├──────────────────────────────────────────────────────────────────────────────────────┤ │ [13] Cancel Save │ ← footer buttons │ [14] (+) (✦) │ ← FABs └──────────────────────────────────────────────────────────────────────────────────────┘ [15] overlays open above all of this: dialog · drawer · popover · toast ``` | # | Part | What it is | Declared with | |---|---|---|---| | 1 | App identity | Title, subtitle, logo, favicon | `title:` / `logo:` on `type: AppShell` · `@Title`, `@Logo`, `@FavIcon` on the `@UI` class | | 2 | Navigation | The menu, drawn by the shell variant | `menu:` · `@Menu` fields, `MenuSupplier` | | 3 | Header widgets | Context pickers, header actions, notification bell, theme toggle, live values | see [the app header](#the-app-header) | | 4 | Breadcrumbs | Where the page sits | `BreadcrumbsSupplier` · [breadcrumbs](/java-user-manual/advanced/breadcrumbs/) | | 5 | Overline | A quiet line above the title | `@Overline` / `OverlineSupplier` | | 6 | Title | The page title (and a placeholder while it is empty) | `title:` · `@Title` / `TitleSupplier`, `@TitlePlaceholder` | | 7 | Badges | Status chips beside the title | `@BadgeInHeader` fields / `BadgeSupplier` | | 8 | Subtitle, timestamp, KPIs | Context under the title; key/value facts | `subtitle:` · `@Subtitle`, `@Timestamp`, `@KPI` fields | | 9 | Peer navigation, record switcher | Previous / next record; jump to any record | `PeerNavigationSupplier`, `RecordSwitcherSupplier` | | 10 | Toolbar | The page's actions; secondary ones collapse into "…" | `toolbar:` · `@Toolbar` methods, `ToolbarSupplier` | | 11 | Banners | Messages above the body: info, success, warning, danger | `@Banner` / `BannerSupplier`, or returned by an action | | 12 | Body | The components of the page: sections, zones, tabs, listings… | `content:` · the view model's fields, or a component tree | | 13 | Footer buttons | The page's closing actions | `buttons:` · `@Button` methods, `ButtonsSupplier` | | 14 | FABs | Floating action buttons, per page or for the whole app | `@Fab` methods | | 15 | Overlays | Dialogs, drawers, popovers, toasts | returned by actions; see [overlays](#overlays) | The page-header parts 5–9 and the banners are page **metadata**, declared in code today; a YAML `Form` or `Listing` has `title`, `subtitle`, `toolbar`, `header`, `buttons` and `footer`. The header grammar itself (one primary action, secondary actions in "…", a leading `EntityHeader` hoisted into the header) is described in [page templates](/ux-patterns/page-templates/). ## The mount A **mount** is an app served at a base path (`/`, `/back-office`). It names its home page and the route files that make it up. Several mounts can live in one project, or be [federated](/mateu-about/ui-federation/) into one console. A mount has no visual presence of its own: what you see is its shell. See [mounts and routes](/concepts/routes-and-mounts/). ## The app shell and its variants The **app shell** is the chrome around every page of a mount: identity, header, navigation and the content area. It is not a page: its content area shows the current route's page. The **variant** decides how navigation is drawn: | Variant | What it looks like | Good for | |---|---|---| | `MENU_ON_TOP` | a horizontal bar; groups open as dropdowns | a standard back office with two levels | | `HAMBURGER_MENU` | a button opening the whole menu in a drawer | many top-level entries; small screens | | `HAMBURGER_SECTIONS` | the hamburger holds the sections, a band under the header holds the current section's entries | large suites organised in sections | | `MENU_ON_LEFT` | a persistent, collapsible sidebar | keeping the whole tree visible while working | | `RAIL` | a compact icon rail on the left | frequent switching between a few areas | | `TABS` | a tab bar | a few peer sections with no hierarchy | | `TILES` | flat top-level entries; an entry with children opens a hub of tiles | deep menus | | `AUTO` (the default) | chosen from the menu's shape, see below | not deciding | How `AUTO` picks, in order: 1. the menu federates a `RemoteMenu` → `MENU_ON_TOP`; 2. a group contains another group (three levels or more) → `TILES`; 3. the menu has groups and more than seven top-level entries → `HAMBURGER_MENU`; 4. the menu has groups → `MENU_ON_TOP`; 5. the menu has no groups at all, however long → `TABS`. An explicit variant always wins. (`MEDIATOR` is internal: the chrome-less shell a CRUD uses inside the content area.) Two shell flags change the chrome itself: - **Command center** (`commandCenter: true` · `@App(commandCenter = true)`): a floating button that opens a full-screen palette unifying navigation, entity search, recent screens and the AI hand-off. See [command center](/ux-patterns/command-center/). - **Chromeless** (`chromeless: true` · `@App(chromeless = true)`): drops the navigation chrome entirely; the command center becomes the way around. Implies the command center. :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: The content area can also be split in two panes (`@App(layout = AppLayout.SPLIT)`), and the `accentColor`/`accentStrip` attributes brand the shell (see [accent colour and strip](/design-systems/accent-strip/)). <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml # specs/ui/app.yaml, bound to the mount root ("") in routes.yaml type: AppShell title: Catalogue variant: AUTO themeToggle: true commandCenter: true menu: - {type: RouteLink, label: Products, route: products} - type: Menu label: Reports submenu: - {type: RouteLink, label: Sales, route: reports/sales} ``` </TabItem> <TabItem label="Java"> ```java @UI("") @Title("Catalogue") @App(value = AppVariant.AUTO, themeToggle = true, commandCenter = true) public class Catalogue { @Menu Products products; @Menu Reports reports; // a class holding @Menu fields becomes a group } ``` C#: `[App(...)]` with `[MenuItem]` methods. Python: `@app(...)` with `@menu_item`. </TabItem> </Tabs> More: [App shell and menus](/concepts/app-shell-and-menus/) (the concept), [App shell as data](/define/yaml/app-shell/) (every YAML key), [`@App`](/java-ui-definition/annotations/app/) (every attribute) and [navigation patterns](/ux-patterns/navigation/) (each variant in detail). ## The app header The right side of the app header hosts app-wide widgets. Each one appears only when the app declares it: | Widget | What it does | Declared with | Pattern page | |---|---|---|---| | Context pickers | Fix a value for every screen: active hotel, company, fiscal year | `@AppContext` field on the app class | [App context](/ux-patterns/app-context/) | | Header actions | Buttons and dropdowns next to the pickers | `AppActionsSupplier` | [App context › header actions](/ux-patterns/app-context/) | | Notification bell | Inbox with unread count and mark-as-read | `NotificationsSupplier` | [Notification inbox](/ux-patterns/notification-inbox/) | | Global search | ⌘K palette searching the menu *and* your data | `GlobalSearchSupplier` | [Global search](/ux-patterns/global-search/) | | Theme toggle | Light / dark (Redwood: light only, ignored) | `themeToggle` | [`@App`](/java-ui-definition/annotations/app/) | | Live header values | Values pushed from the server (a counter, a clock) | `headerValues:` · `HeaderValuesSupplier` | [Live header values](/ux-patterns/live-header-values/) | | Widgets | Any component (a version tag, a status badge) | `widgets:` | [App shell as data](/define/yaml/app-shell/) | | Open on mobile | A QR code that opens the current screen in the Mateu app | `mobileQr` | [Open on mobile](/ux-patterns/mobile-app/) | App-wide behaviours that are not widgets: [app shortcuts and quick launch](/ux-patterns/app-shortcuts/) (`@AppShortcut`, `shortcuts:`), [access keys](/ux-patterns/keyboard-shortcuts/) (`accessKeys`), the [idle-session warning](/ux-patterns/idle-session/) and the [embedded AI chat](/ai/) (`@AI`, a floating button at the bottom right). ## Navigation and menus A menu is a list of entries. Every **leaf** either routes somewhere or runs something: | Entry | What a click does | |---|---| | `RouteLink` | navigates to a route of the mount (or a full URL) | | `RuleLink` | runs an action instead of navigating | | `Menu` | a group of entries, nestable | | `RemoteMenu` | the menu of another Mateu service, fetched at runtime | Two presentations change how a group opens: - **Card menus** (`@Menu(display = MenuDisplay.cards)`, or `presentation: {display: cards}`): the group opens as a panel of cards, each with a description and an image or icon. See [card menus](/java-user-manual/build/navigation-and-menus/#card-menus-a-group-that-opens-as-cards). - **Remote menus**: a shell composes the menus of independent services, so several teams' UIs appear as one console. See [shell and remote menus](/mateu-about/shell-and-remote-menus/). Entries the caller may not open are not sent at all (a `RouteLink` inherits its route's access rules). The home page is the shell's `homeRoute`, else the mount's `home:`, else the first navigable entry. More: [navigation and menus](/java-user-manual/build/navigation-and-menus/). ## The content area The content area shows the page of the current route. Navigating replaces it; the shell stays. Its width follows the page, not the shell: each page is **fixed** (capped at 1408 px and centred), **full width** (fluid with side gutters) or **edge to edge** (no margins). See [page width](/ux/page-types/#page-width). Inside a page, parts of the screen can be independent **islands**: an embedded view or [micro-frontend](/java-ui-definition/components/micro-frontend/) with its own state and actions, which re-renders on its own. See [component communication](/ux-patterns/component-communication/). ## Page anatomy A page has five regions. Most pages use some of them; a [page type](/ux/page-types/) is largely a convention about which regions it fills and how. 1. **Header**: breadcrumbs, overline, title, badges, subtitle, timestamp, KPIs, peer navigation, record switcher and toolbar. A page can also open with a [welcome banner](/ux-patterns/welcome-page/) (`@WelcomeBanner`), a hero above the content. When a page's content starts with an [`EntityHeader`](/ux-patterns/entity-header/), the renderer hoists it into this header. 2. **Banners**: page messages between the header and the body, static (`@Banner`, `BannerSupplier`) or returned by an action (`PageBanner`), optionally closeable or timed. For a message *inside* the body, use a [notice](/ux-patterns/notice/). 3. **Body**: the components. In code, fields group into `@Section` cards, which can sit side by side in `@Zones`, become `@Tab`s, sit side by side with `@FoldedLayout`, get a sticky index with [`@Toc`](/ux-patterns/sections-index/), or place one panel aside with `@Aside`. A `ContentLayout` gives the *main + aside + footer* grammar to any page. 4. **Footer buttons**: the closing actions (`@Button` methods, `buttons:` in YAML). 5. **FABs**: floating action buttons (`@Fab`), scoped to the page or, on the app class, to the whole app. They stack above the AI and command-center buttons. ![KPIs in the page header](/images/docs/components/kpi.png) ![Banners between the page header and the body](/images/docs/components/banners.png) Two modifiers change the whole page: [`@Compact`](/ux-patterns/high-density/) for dense operational screens, and [`@AutoSave`](/ux-patterns/autosave/) for screens without a save button. ## Overlays An overlay opens above the page without leaving it. An action returns it, and `UICommand.closeModal()` closes the topmost one (optionally emitting an event the page reacts to). | Overlay | Use it for | Pattern page | |---|---|---| | `Dialog` | a short, focused interaction that must be answered | [Dialog](/java-ui-definition/components/dialog/) | | `ConfirmDialog` | confirming a destructive action (`@Action(confirmationRequired = true)` builds one for you) | [Confirm dialog](/java-ui-definition/components/confirm-dialog/) | | `Drawer` (side) | editing or reading more about something without losing the page; CRUD create/edit with `editInDrawer()` | [Drawer](/ux-patterns/drawer/) | | `Drawer` (bottom) | a docked, collapsible panel under a canvas | [Bottom drawer](/ux-patterns/drawer/) | | `Popover` | details on hover or click | [Hover details](/ux-patterns/hover-details/) | | `ActionPanel` | a categorised "I want to…" menu of actions | [Action panel](/ux-patterns/action-panel/) | | Toasts | messages returned by actions, including undoable ones | [Undo](/ux-patterns/undo/) | Overlays trap focus and give it back when they close; see [accessibility](/ux-patterns/accessibility/). ## Next - [Page types](/ux/page-types/): what fills the content area. - [Components](/ux/components/): the catalogue every region is built from. --- # Components URL: https://mateu.io/ux/components/ > The Mateu component catalogue organised by role: layout, fields and input, display, data and collections, navigation, feedback, overlays, charts and specialised canvases, composition. Plus field types and stereotypes, and how renderers map components. Every page, whether it is written in YAML, built fluently in code or derived from a class, is a tree of components from **one catalogue**. In YAML the `type:` of a node is the component's name; in Java the same name is a record in `io.mateu.uidl.data` with a builder; C# and Python have the same names. The catalogue's JSON Schema, `specs-schema.json`, is generated from those records, so the schema, the visual editor's palette and the renderers cannot disagree. This page lists the catalogue by **role**, one line per component, with a link to its page where there is one. Annotated view models produce the same components: a field becomes a `FormField`, a `List<Row>` a grid, a `@Section` a card, a `@Button` method a `Button`. ## Layout Containers that arrange other components. | Component | What it is for | |---|---| | [`VerticalLayout`](/java-ui-definition/components/vertical-layout/) / [`HorizontalLayout`](/java-ui-definition/components/horizontal-layout/) | stack children down or across; the everyday containers | | [`FormLayout`](/java-ui-definition/components/form-layout/) | responsive columns of fields (`FormRow`, `FormItem`, `FormSection`, `FormSubSection` structure it) | | `ContentLayout` | deprecated — the content-page grammar (`main` + `aside` + `footer`) is a `ResponsiveGrid` with named areas (`gridTemplateAreas` + `Slotted` children, `stickyAreas` for a pinned aside) | | [`Card`](/java-ui-definition/components/card/) | a framed group with a title; what a `@Section` becomes | | [`TabLayout`](/java-ui-definition/components/tab-layout/) / [`AccordionLayout`](/java-ui-definition/components/accordion-layout/) / [`Details`](/java-ui-definition/components/details/) | groups the user switches between, or expands | | [`SplitLayout`](/java-ui-definition/components/split-layout/) / [`MasterDetailLayout`](/java-ui-definition/components/master-detail-layout/) | two resizable panes; a list with its detail | | `ResponsiveGrid` + `DashboardPanel` | a responsive grid of titled tiles ([dashboard](/ux-patterns/dashboard/)); `DashboardLayout` is deprecated | | `FoldoutLayout` + `FoldoutPanel` | an overview with lateral fold-out panels ([foldout](/ux-patterns/foldout/)) | | `HeroSection` | a large title band with optional image and calls to action ([welcome page](/ux-patterns/welcome-page/)) | | [`BoardLayout`](/java-ui-definition/components/board-layout/), `ResponsiveGrid` | rows and columns of tiles | | [`CarouselLayout`](/java-ui-definition/components/carousel-layout/), [`Scroller`](/java-ui-definition/components/scroller/), [`Container`](/java-ui-definition/components/container/), [`FullWidth`](/java-ui-definition/components/full-width/), `Div` | carousels, scroll areas, plain wrappers | ## Fields and input | Component | What it is for | |---|---| | [`Form`](/java-ui-definition/components/form/) | a page or region with a header, fields and buttons | | [`FormField`](/java-ui-definition/components/form-field/) | one input, bound to `state.<id>`; its data type and stereotype pick the widget (see [below](#fields-and-field-types)) | | `CustomField` | a field whose value is a component, so any component can sit in a form row | | [`Button`](/java-ui-definition/components/button/) / `ButtonGroup` | run an action, navigate, or open a menu | | `DropZone` | a target that rows can be dragged onto ([drag to a destination](/ux-patterns/drag-to-a-destination/)) | | `AddOnPicker`, `PaymentPicker`, `ResourceGrid` | task-specific pickers ([add-on picker](/ux-patterns/addon-picker/), [payment picker](/ux-patterns/payment-picker/), [resource grid](/ux-patterns/resource-grid/)) | | `MessageInput` | a chat-style input ([AI chat](/ai/)) | ## Display Read-only presentation of values and records. | Component | What it is for | |---|---| | [`Text`](/java-ui-definition/components/text/), [`Markdown`](/java-ui-definition/components/markdown/), [`Image`](/java-ui-definition/components/image/), [`Icon`](/java-ui-definition/components/icon/) | text in five sizes, formatted text, pictures and icons | | [`Avatar`](/java-ui-definition/components/avatar/), `AvatarGroup`, [`Badge`](/java-ui-definition/components/badge/) | people and status chips | | `EntityHeader` | a record's banner: title, badges, facts, a metric ([entity header](/ux-patterns/entity-header/)) | | [`KPI`](/java-ui-definition/components/kpi/), `MetricCard`, `Scoreboard`, `Stat` | key numbers, alone or as a band ([stat](/ux-patterns/stat/)) | | `Meter`, `TaskProgress` | a value against a limit; done/total progress ([meter](/ux-patterns/meter/), [task progress](/ux-patterns/task-progress/)) | | `BulletedList`, `StatusList`, `Checklist`, `Separator` | lists of items, of statuses, of tasks; a divider ([status list](/ux-patterns/status-list/), [checklist](/ux-patterns/checklist/)) | | `Timeline`, `CommentThread`, `FileList` | activity, conversation, attachments ([timeline](/ux-patterns/timeline/), [comment thread](/ux-patterns/comment-thread/), [file list](/ux-patterns/file-list/)) | | `Ledger`, `ProcessMonitor`, `RecordMerge` | a folio breakdown, process health, merging two records ([ledger](/ux-patterns/ledger/), [process monitor](/ux-patterns/process-monitor/), [record merge](/ux-patterns/record-merge/)) | | `CalloutCard`, `OfferCard`, `ComparisonCard`, `PricingTable`, `FeatureGrid`, `Testimonials`, `Faq` | marketing-style and landing blocks ([callout card](/ux-patterns/callout-card/), [offer card](/ux-patterns/offer-card/), [comparison card](/ux-patterns/comparison-card/), [pricing table](/ux-patterns/pricing-table/), [feature grid](/ux-patterns/feature-grid/), [testimonials](/ux-patterns/testimonials/), [FAQ](/ux-patterns/faq/)) | | `OrgChart` | a hierarchy of people or units ([org chart](/ux-patterns/org-chart/)) | ## Data and collections | Component | What it is for | |---|---| | `Listing` + `GridColumn` | the searchable, filterable, paginated collection: table, list, cards, tree or master-detail ([filters and listing](/ux-patterns/filters-and-listing/)) | | [`Grid`](/java-ui-definition/components/grid/), `GridGroupColumn` | a plain or editable table, with grouped headers ([editable table](/ux-patterns/editable-table/)) | | [`VirtualList`](/java-ui-definition/components/virtual-list/) | a long, lazily rendered list | | `TaskQueue` | counted buckets of actionable cards ([task queue](/ux-patterns/task-queue/)) | | `Kanban` | cards in columns ([kanban](/ux-patterns/kanban/)) | | `Calendar` | month, week, day and list views of events ([calendar](/ux-patterns/calendar/)) | | `MatrixGrid` | rows × dates with collapsible sections and in-place editing ([matrix grid](/ux-patterns/matrix-grid/)) | | `PlanningBoard` | resources × days tape chart, drag to move ([planning board](/ux-patterns/planning-board/)) | | `Gantt` | tasks on a timeline ([Gantt](/ux-patterns/gantt/)) | ## Navigation | Component | What it is for | |---|---| | Menu entries: `RouteLink`, `RuleLink`, `Menu`, `RemoteMenu` | the app menu; see [navigation and menus](/ux/app-structure/#navigation-and-menus) | | `MenuBar`, `ContextMenu` | a bar of menus; a menu on right-click (or left-click) around another component | | [`Directory`](/java-ui-definition/components/directory/) | a categorised directory of links, for landing pages | | [`Breadcrumbs`](/java-ui-definition/components/breadcrumbs/), [`Anchor`](/java-ui-definition/components/anchor/), `Tab` | where you are; a link; one tab of a `TabLayout` | | `ProgressSteps` | where you are in a process ([progress steps](/ux-patterns/progress-steps/)) | ## Feedback | Component | What it is for | |---|---| | `Notice` | an inline message strip inside the body, with an optional action ([notice](/ux-patterns/notice/)) | | [`Notification`](/java-ui-definition/components/notification/) | a toast (actions usually return a `Message` instead) | | [`ProgressBar`](/java-ui-definition/components/progress-bar/) | progress of a step or a job | | `EmptyState`, `Skeleton` | nothing to show yet; still loading ([empty states and skeletons](/ux-patterns/empty-states-and-skeletons/)) | | `NotFound` | a route that does not exist ([not found](/ux-patterns/not-found/)) | | [`Tooltip`](/java-ui-definition/components/tooltip/), [`CookieConsent`](/java-ui-definition/components/cookie-consent/) | hints; the consent banner | Page banners are page metadata rather than components; see [page anatomy](/ux/app-structure/#page-anatomy). ## Overlays | Component | What it is for | |---|---| | [`Dialog`](/java-ui-definition/components/dialog/), [`ConfirmDialog`](/java-ui-definition/components/confirm-dialog/) | a modal question; a confirmation | | `Drawer` | a side or bottom panel over the page ([drawer](/ux-patterns/drawer/)) | | [`Popover`](/java-ui-definition/components/popover/) | details on hover or click ([hover details](/ux-patterns/hover-details/)) | | `ActionPanel` | a categorised "I want to…" overlay ([action panel](/ux-patterns/action-panel/)) | ## Charts and specialised canvases | Component | What it is for | |---|---| | [`Chart`](/java-ui-definition/components/chart/), `TrendChart`, `Funnel`, `Heatmap` | bar, line, pie and friends; a dependency-free trend line; a funnel; a calendar heatmap ([trend chart](/ux-patterns/trend-chart/), [funnel](/ux-patterns/funnel/), [heatmap](/ux-patterns/heatmap/)) | | [`Map`](/java-ui-definition/components/map/) | a street map with clickable markers | | `Bpmn`, `Workflow` | a BPMN diagram; a workflow-definition editor | | `Chat`, `MessageList` | a conversation ([AI chat](/ai/)) | ## Composition and extension These carry no look of their own; they assemble or delegate. | Component | What it is for | |---|---| | `Partial` | a named piece of layout spliced in by reference ([partials](/define/yaml/partials/)) | | `ComponentRef` | a named business component bound to a data source ([business components](/java-ui-definition/component-catalogue/)) | | `CustomComponent` | a rendering the catalogue does not have, registered per renderer ([custom components](/java-ui-definition/custom-components/)) | | [`Element`](/java-ui-definition/components/element/) | any HTML element or web component by tag name ([custom web components](/java-user-manual/advanced/custom-web-components/)) | | [`MicroFrontend`](/java-ui-definition/components/micro-frontend/), `EmbeddedView` | another Mateu UI, or another view, embedded as an island | | `FutureComponent`, `Slotted` | a component that arrives later; a child placed in a named slot | | `State`, `AppState`, `Data`, `AppData` | not visual: values an action returns to update a [state scope](/concepts/state-and-triggers/) | The full, always-current list is the generated schema, [`specs-schema.json`](https://github.com/miguelperezcolom/mateu/blob/master/backend/shared/uidl/specs-schema.json). ## Fields and field types A `FormField` (or an annotated field) is drawn according to two properties: - **`dataType`**: what the value is: `string`, `integer`, `number`, `bool`, `date`, `time`, `dateTime`, `dateRange`, `money`, `status`, `file`, `array`, `range`, `component`, `menu`, `action`, `actionGroup`. - **`stereotype`**: how to edit or show it: `regular`, `textarea`, `richText`, `html`, `markdown`, `email`, `password`, `select`, `combobox`, `listBox`, `radio`, `checkbox`, `toggle`, `multiSelect`, `treeSelect`, `choice`, `searchable`, `slider`, `stars`, `color`, `icon`, `link`, `money`, `badge`, `plainText`, `bulletedList`, `grid`, `image`, `uploadableImage`, `fileUpload`, `signature`, `camera`, `dateRange`, `numberRange`, `popover`, `button`, `primary`. In code, both are inferred from the Java, C# or Python type (a `LocalDate` is a date picker, a small enum is a radio group, a `List<Row>` is a grid) and overridden with `@Stereotype` or a shorthand annotation (`@Badge`, `@UploadableImage`, `@Signature`, `@TreeSelect`…). See [field stereotypes](/java-user-manual/concepts/field-stereotypes/) and [field annotations](/java-ui-definition/annotations/field-types/). To name a **domain concept** once (`OrderStatus`, `Money`, `Email`) and reuse it on every field and column, declare a [field type](/java-ui-definition/field-types/) in `types.yaml` (`fieldType: OrderStatus`) or, for annotated classes, a [semantic annotation](/java-ui-definition/annotations/semantic-annotations/). ## How renderers map components A component on the wire says *what* to show; each renderer decides *how*, with its own widgets: | Renderer | Paints components with | Details | |---|---|---| | Vaadin (web) | Vaadin web components, plus Mateu's own design-neutral elements for the rest | [Vaadin](/design-systems/vaadin/) | | Redwood (web) | Oracle JET and Redwood components, inside a Visual Builder app | [Redwood](/design-systems/oracle-redwood/), [Redwood coverage](/reference/parity/#redwood-component-coverage) | | React Native (mobile) | native views | [The Mateu app](/native/react-native/) | | IntelliJ (desktop) | Swing components in tool windows and editor tabs | [IntelliJ](/native/) | A renderer that has no view for a component shows a visible *unsupported* placeholder instead of silently dropping it, which is what the conformance suite counts. What a renderer must implement, and the **Core / Standard / Full** conformance levels, are in the [renderer contract](/design-systems/renderer-contract/). Which feature works where is in the [parity matrix](/reference/parity/). --- # Extending the UI URL: https://mateu.io/ux/extending/ > The extension ladder, from least to most effort: semantic annotations, field types, reusable pieces, composed pages, custom components and web components, component adapters, micro-frontends, design systems and theming, and writing your own renderer. When to use which. The catalogue and the page templates cover most business screens. When they don't, Mateu has a **ladder** of extension points. Each rung costs more than the one above it and gives up a little more of what Mateu does for you, so start at the top and descend only as far as the problem needs. | # | Rung | Use it when | Effort | Ports to every renderer? | |---|---|---|---|---| | 1 | [Explicit declarations](#1-say-what-you-want-explicitly) | an inferred decision is wrong for this screen | none | yes | | 2 | [Semantic annotations](#2-name-your-configuration-semantic-annotations) | the same annotations repeat on many fields | a few lines | yes | | 3 | [Field types](#3-name-your-domain-concepts-field-types) | a domain concept (`Money`, `OrderStatus`) repeats across fields and columns | a YAML entry | yes | | 4 | [Partials and business components](#4-reuse-a-piece-partials-and-business-components) | a piece of screen repeats across pages | a YAML file or a class | yes | | 5 | [A composed page](#5-compose-the-page-yourself) | the whole screen fits no template | a component tree | yes | | 6 | [Component adapters](#6-render-a-foreign-object-componentadapter) | an object can't or shouldn't carry Mateu annotations | an adapter class | yes | | 7 | [Micro-frontends and remote UIs](#7-embed-another-ui-micro-frontends-and-federation) | another team or service owns part of the screen | configuration | yes | | 8 | [Custom components and web components](#8-draw-something-new-custom-components) | you need a drawing the catalogue does not have | a renderer per target | **no**, each renderer registers it | | 9 | [Design systems and theming](#9-change-the-look-design-tokens-and-theming) | the app must look like your brand | tokens, once | per renderer | | 10 | [Your own renderer](#10-paint-it-somewhere-new-your-own-renderer) | a target or design system Mateu does not paint | a renderer | it *is* the renderer | Rungs 1 to 7 stay inside the model: what you build is data on the wire, so every renderer paints it, and it works in a static bundle when it needs no server. Rungs 8 to 10 add rendering code, which is why they come last. ## 1. Say what you want, explicitly Before extending anything, check whether you only disagree with an inferred decision. Explicit declarations always win over inference, and removing them gives inference back: `@Section`, `@Zones`, `@Tab`, `@Toc`, `@Aside`, `@PageWidth`, `@PageTemplate`, `@Compact`, `@Stereotype`… in code, and the equivalent keys in YAML. See the [ladder of control](/the-mateu-way/#the-ladder-of-control) and [layout inference](/ux-patterns/layout-inference/). ## 2. Name your configuration: semantic annotations :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: When the same combination of annotations appears again and again, fold it into one annotation that speaks your domain: ```java @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.FIELD) @Stereotype(FieldStereotype.money) @Label("Total amount") @Help("Taxes included") public @interface TotalAmount {} @TotalAmount BigDecimal total; ``` Every field, method and class annotation of Mateu can be composed this way. No new code path is involved, only a name. See [semantic annotations](/java-ui-definition/annotations/semantic-annotations/) and [build your domain vocabulary](/java-ui-definition/domain-vocabulary/). ## 3. Name your domain concepts: field types The data-side equivalent: declare `OrderStatus` once (label, data type, stereotype, options, status tones, alignment) and reference it with `fieldType:` from any field or column, in YAML or in code (`FieldTypeCatalogSupplier`). What the field declares itself still wins. ```yaml # specs/ui/types.yaml type: Types types: - id: OrderStatus dataType: status options: - {value: OPEN, label: Open} - {value: SHIPPED, label: Shipped} tones: {OPEN: warning, SHIPPED: success} ``` See [field types](/java-ui-definition/field-types/). **A new kind of field.** There is no registry for new stereotypes. When a field needs a widget the catalogue does not have, make the field hold a component (a `CustomField`, or in code a field typed as a component) and put a [custom component](#8-draw-something-new-custom-components) or a web component in it. ## 4. Reuse a piece: partials and business components - A [**partial**](/define/yaml/partials/) is a named piece of layout spliced into any page by `ref`. It is resolved before the wire, so no renderer knows about it. - A [**business component**](/java-ui-definition/component-catalogue/) is a named composition *bound to a data source* (an agency selector = a select + a source), declared in `components.yaml` or a `ComponentCatalogSupplier` and used with `ComponentRef`. Both are made of catalogue components, so they port to every renderer and run with no backend. When in doubt between a business component and a custom component, it is almost always a business component. ## 5. Compose the page yourself When the whole screen is none of the [six page types](/ux/page-types/), build the tree yourself: in YAML a definition already *is* a tree; in code implement `ComponentTreeSupplier` and return it. You keep state, actions, validation, routing and the surrounding shell, and you can still declare the page's type. See [when a screen does not fit](/java-user-manual/advanced/escaping-the-framework/) and the [component tree](/java-ui-definition/the-component-tree/). ## 6. Render a foreign object: ComponentAdapter A plain or legacy domain object with no Mateu annotations can be rendered by registering a `ComponentAdapter<T>`: it turns the object into components, state and actions, and rebuilds the object from the state when an action comes back. It works for a whole page and for a nested field, which becomes its own island. See [ComponentAdapter](/java-ui-definition/interfaces/component-adapter/). ## 7. Embed another UI: micro-frontends and federation - [`MicroFrontend`](/java-ui-definition/components/micro-frontend/) embeds a route of another Mateu UI inside a page, as an independent island. - A [`RemoteMenu`](/mateu-about/shell-and-remote-menus/) brings another service's menu into the shell, so independently deployed UIs form one console. - The reverse, a Mateu screen inside React, Angular, Vue, Visual Builder or plain HTML, is [embedding](/mateu-about/embed/). See [UI federation](/mateu-about/ui-federation/) for the whole picture. ## 8. Draw something new: custom components When nothing in the catalogue fits and no composition will do (a seat map, a bespoke visualisation), declare a `CustomComponent` with a `name`, `props` and slotted `content`, and register a renderer for that name in each renderer that should draw it. On the web: ```ts import { registerCustomComponent } from "mateu"; import { html } from "lit"; registerCustomComponent("seat-map", (props, children) => html`<my-seat-map rows=${props.rows as number}>${children}</my-seat-map>`); ``` A renderer that has not registered the name shows a visible *unsupported* placeholder, never a broken screen. See [custom components](/java-ui-definition/custom-components/). For an existing **web component** (a 3D viewer, a third-party widget), the web renderers also accept an [`Element`](/java-ui-definition/components/element/) with any tag name, its attributes and event bindings, plus a script to load it. See [custom web components](/java-user-manual/advanced/custom-web-components/). ## 9. Change the look: design tokens and theming A brand is a **token layer** set once (colours, typography, radii, density), not per-screen styling. Each renderer exposes its design system's tokens; the shell adds an [accent colour and strip](/design-systems/accent-strip/). Per-page density is `@Compact`; per-page width is `@PageWidth`. Inline `style`/`cssClasses` exist on every component, but they are a renderer-specific escape and do not travel well. See [branding and design tokens](/design-systems/branding-and-design-tokens/) and, for designers, the [Figma pipeline](/design-systems/figma/). ## 10. Paint it somewhere new: your own renderer A renderer receives the wire's UI increments and paints them with its own widgets. The [renderer contract](/design-systems/renderer-contract/) says what it must do and defines three conformance levels (**Core**, **Standard**, **Full**) measured by a shared fixture suite, so "done" is a number, not a feeling. Start from [bring your own design system](/design-systems/bring-your-own-design-system/) and the [reference renderer](/design-systems/reference-renderer/). ## Which rung? | Your situation | Rung | |---|---| | "The form puts these fields in tabs, I want them stacked" | 1 | | "Every supplier field has the same four annotations" | 2 | | "`Money` is right-aligned with two decimals everywhere" | 3 | | "Every order page has the same customer block" | 4 | | "This screen is a custom console, not a list or a record" | 5 | | "I must show a legacy DTO I can't annotate" | 6 | | "The billing team owns that panel and deploys it separately" | 7 | | "We need an interactive seat map" | 8 | | "It has to look like our corporate design" | 9 | | "We want it in our in-house component library" | 10 | --- # Page types URL: https://mateu.io/ux/page-types/ > Every Mateu page is one of six types: collection, detail, form, process, dashboard or landing. What each is for, its templates and archetypes, its anatomy, its default width, a minimal example, and how a page declares or infers its type. import { Tabs, TabItem } from '@astrojs/starlight/components'; Every page of a Mateu app belongs to one of **six page types**. The type is a business decision (*what is the user doing on this screen?*), not a layout decision, and it is the first thing to settle for each screen. The names follow the families of the Oracle Redwood page templates, the clearest public taxonomy for business UIs, and every page carries its type on the wire as `pageType`. | Type | The user is… | Typical templates | Default width | |---|---|---|---| | [**Collection**](#collection) | finding things in a set: searching, listing, opening, editing | CRUD, smart search, to-do list, calendar, collection detail, data management | from the content | | [**Detail**](#detail) | looking at *one* thing in depth | item overview, general overview, foldout, Gantt page | from the content | | [**Form**](#form) | completing one task: some fields, one action | create & edit, advanced create & edit, task-centric page | fixed | | [**Process**](#process) | moving through steps toward a result | wizard (bar, steps, rail), guided import | fixed | | [**Dashboard**](#dashboard) | monitoring numbers to decide what needs attention | dashboard | from the content | | [**Landing**](#landing) | arriving: orientation and ways in | welcome, hero search | fixed | To pick a type, ask at most three questions, in order: 1. **Many records or one?** Many → *collection*. One → *detail*. 2. **Is the user changing something?** In one shot → *form*. Across steps → *process*. 3. **Neither?** Watching numbers → *dashboard*. It's the front door → *landing*. Then pick the template within the type with the decision guide, [Choosing a page template](/ux-patterns/choosing-a-page-template/), and see every template with its demo route in [Page templates](/ux-patterns/page-templates/). ## How a page gets its type A page's type is resolved in this order: 1. **Declared.** In Java `@PageTemplate(PageType.DASHBOARD)`, in C# `[PageTemplate(PageType.Dashboard)]`, in Python `@page_template(PageType.DASHBOARD)`. In YAML, a definition declares it with the `pageType:` key (for example `pageType: dashboard`), using the same six names as the wire. 2. **From the archetype.** Each archetype belongs to one type (the tables below say which). 3. **From the shape.** A `Listing` or CRUD is a collection; a view with `MetricCard` fields is a dashboard; a view made only of `Button` and component fields that `@AutoPage` composes as a welcome page is a landing; anything else is a form. Inference goes one step further for the two shapes Mateu can derive entirely: with [`@AutoPage`](/ux-patterns/layout-inference/#page-level-inference-autopage), a class of `MetricCard` fields is *composed* as a dashboard, and a class of `Button` fields and panels as a welcome page. For other shapes Mateu only advises: a plain form that looks like a known template (a selectable list next to a detail pane, for instance) logs a one-time hint naming the archetype. Below the type, [`@AutoLayout`](/ux-patterns/layout-inference/) infers sections, tabs and widgets. What the type changes: - the page's **default width** (below); - the `data-page-type` attribute on the rendered page, a hook for stylesheets; - a shared vocabulary for docs, conformance tests and the IDE page templates. ## Page width Width is the first parameter of every page template: | Width | What it does | Good for | |---|---|---| | **Fixed** | caps the content column at 1408 px and centres it | text and forms, which get harder to read when too wide | | **Full width** | fluid, keeping 24 px side gutters | dense grids and tables | | **Edge to edge** | no side margins | canvases: Gantt, planning board, foldout, map | Resolution order: a declaration (`@PageWidth(FULL_WIDTH)`, C# `[PageWidth(PageWidthStyle.FullWidth)]`, Python `@page_width(PageWidth.FULL_WIDTH)`, or the `PageWidthSupplier` hook) wins. Otherwise **form, process and landing pages are fixed**, and collection, detail and dashboard pages are inferred from their content: full-bleed canvases (Gantt, planning board, kanban, BPMN, map) → edge to edge, a dense or inline-editable CRUD → full width, anything else → fixed. Three archetypes declare theirs: `Foldout` and `GanttPage` are edge to edge, `DataManagement` is full width. In YAML, the IDE's **New › Mateu › Page…** wizard writes the chosen width into the root layout's `style` (see [IDE tooling](/native/ide-tooling/)). --- ## Collection **For:** finding, comparing and acting on records in a set. **Anatomy:** page header with the primary action (*New*), the smart search bar (free text + typed filter chips + saved views), the results (table, list, cards, tree or master-detail), pagination, and selection-driven bulk actions. A row opens the record, or edits it in a drawer. **Components you meet here:** `Listing`, `GridColumn`, the filter bar, `Badge`/status columns, `EmptyState`, `TaskQueue`, `Calendar`, `Kanban`. | Template | Archetype or piece | Detail | |---|---|---| | Create & edit (CRUD) | `AutoCrud<T>` / `Crud<…>` | [Create and edit](/ux-patterns/create-and-edit/) | | Listing with capabilities | `Listing<Row>` + `Searchable`, `Filterable`, `Navigable`, `Editable`, `Creatable`, `Deletable` | [Capability listings](/java-user-manual/build/capability-listings/) | | Smart search page | `SmartSearchPage<Filters, Row>` | [Smart search](/ux-patterns/smart-search/) | | To-do list | `TodoList<Row>` | [To-do list](/ux-patterns/to-do-list/) | | Calendar | `CalendarPage` | [Calendar](/ux-patterns/calendar/) | | Collection detail | `CollectionDetail<Row>` | [Collection detail](/ux-patterns/collection-detail/) | | Data management (grid ⇄ Gantt) | `DataManagement` | [Data management](/ux-patterns/data-management/) | | Split view, tree | `@SplitCrud`, `GridLayout.tree` | [Split view](/ux-patterns/split-view/), [Tree CRUD](/ux-patterns/tree-crud/) | :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: Listing behaviours worth knowing: [filters and listing](/ux-patterns/filters-and-listing/), [bulk actions](/ux-patterns/bulk-actions/), [saved views](/ux-patterns/saved-views/), [totals and grouping](/ux-patterns/aggregates/), [column chooser](/ux-patterns/column-chooser/), [inline editing](/ux-patterns/inline-crud-editing/), [guided import](/ux-patterns/guided-import/). <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml # specs/ui/orders.yaml: rows from a named source; a row opens the record type: Listing title: Orders searchable: true rowsSource: ref: orders rowRoute: orders/${row.id} toolbar: - {type: Button, label: New, actionId: new, buttonStyle: primary} filters: - {type: FormField, id: status, label: Status, dataType: string, stereotype: select, options: [{value: open, label: Open}, {value: closed, label: Closed}]} columns: - {type: GridColumn, id: customerName, label: Customer, sortable: true} - {type: GridColumn, id: total, label: Total, dataType: money, align: end} - {type: GridColumn, id: status, label: Status, dataType: status} ``` </TabItem> <TabItem label="Java"> ```java @UI("/products") public class Products extends AutoCrud<Product> { @Override public CrudStore<Product> store() { return productStore; // your CrudStore<Product> } } ``` C#: `class Products : Crud<Product>`. Python: `class Products(Crud[Product])`. </TabItem> </Tabs> ![A CRUD listing: search, toolbar, rows](/images/docs/admin-panel/products-list-full-crud.png) ## Detail **For:** understanding one record in depth, and moving to its peers. **Anatomy:** a rich page header (title, status badges, KPIs, timestamp, peer navigation or a record switcher), then the record's information grouped into panels: a sticky key-info panel and tabs, property cards, lateral fold-out panels, or a canvas with a docked detail. **Components you meet here:** `EntityHeader`, `Card` with property-list sections, `TabLayout`, `FoldoutLayout`, `ContentLayout` (main + aside), `Timeline`, `Gantt`. | Template | Archetype or piece | Detail | |---|---|---| | Item overview | `ItemOverview` | [Item overview](/ux-patterns/item-overview/) | | General overview | `GeneralOverview<Row>` | [General overview](/ux-patterns/general-overview/) | | Foldout | `Foldout` | [Foldout](/ux-patterns/foldout/) | | Gantt page | `GanttPage` | [Gantt](/ux-patterns/gantt/) | | Master-detail, editable view | `MasterDetailView`, `EditableView` / `AutoEditableView` | [Editable view](/java-user-manual/build/editable-view/), [master-detail](/java-user-manual/build/master-detail/) | | Waterfall detail | composition: `EntityHeader` + full-width cards | [Waterfall detail](/ux-patterns/waterfall-detail/) | | Detail without leaving the page | a read-only `Drawer` | [Drawer](/ux-patterns/drawer/) | <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml # Key information on the left, the rest of the record in tabs on the right type: HorizontalLayout content: - type: Card style: "flex: 0 0 22rem; position: sticky; top: 0;" title: {type: Text, text: Ergonomic chair EC-200} content: type: FormLayout content: - {type: FormField, id: sku, label: SKU, dataType: string, readOnly: true, propertyRow: true} - {type: FormField, id: price, label: Price, dataType: money, readOnly: true, propertyRow: true} - type: TabLayout tabs: - {type: Tab, label: Details, active: true, content: {type: Text, text: Details go here}} - {type: Tab, label: History, content: {type: Text, text: History goes here}} ``` </TabItem> <TabItem label="Java"> ```java @UI("/product/:id") @Title("Ergonomic chair EC-200") public class ProductOverview extends ItemOverview { Markdown keyInfo = new Markdown("**SKU:** EC-200-BLK · **Price:** 349 €", null, null); @Panel(title = "Specifications") Markdown specs = new Markdown("| Property | Value | …", null, null); @Panel(title = "Reviews") Markdown reviews = new Markdown("⭐⭐⭐⭐⭐ …", null, null); } ``` The first component field without `@Panel` is the sticky key-info panel; each `@Panel` field is a tab. </TabItem> </Tabs> ![An item overview: key-info panel and tabs](/images/docs/item-overview/product-overview.png) ## Form **For:** completing one task: enter or change some fields and run one action. **Anatomy:** page header (title, perhaps a timestamp and KPIs), the fields grouped into sections, validation messages at the field, and the closing actions in the footer (*Cancel*, *Save*). Long forms add a sticky section index (`@Toc`) or a contextual side panel (`@Aside`). **Components you meet here:** `Form`, `FormLayout`, `FormField` with its [stereotypes](/ux/components/#fields-and-field-types), `FormSection`, `Notice`, `Button`. | Template | Archetype or piece | Detail | |---|---|---| | Create & edit | a plain `@UI` class, or the forms of an `AutoCrud` | [Create and edit](/ux-patterns/create-and-edit/) | | Advanced create & edit | sections + `@Toc` or `@Aside`, header extras | [Advanced create & edit](/ux-patterns/advanced-create-and-edit/) | | Task-centric page | one task, one primary action | [Task-centric page](/ux-patterns/task-centric/) | | Partial forms | folded or optional groups | [Partial forms](/ux-patterns/partial-forms/) | <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml type: Form title: New customer content: - type: FormLayout content: - {type: FormField, id: name, label: Name, dataType: string, required: true} - {type: FormField, id: email, label: Email, dataType: string, stereotype: email} - {type: FormField, id: notes, label: Notes, dataType: string, stereotype: textarea, colspan: 2} buttons: - {type: Button, label: Cancel, actionId: cancel, buttonStyle: secondary} - {type: Button, label: Save, actionId: save, buttonStyle: primary} ``` Bind it to a route with a view model that handles `save`, or give it an `actions:` entry with a `restAction` for a page with no backend. </TabItem> <TabItem label="Java"> ```java @UI("/feedback") @AutoLayout public class Feedback { @NotEmpty String subject; @Stereotype(FieldStereotype.textarea) String details; @Button Message send() { return new Message("Thanks!"); } } ``` </TabItem> </Tabs> ![A form: fields, validation and footer buttons](/images/docs/admin-panel/new-product-form-empty.png) ## Process **For:** reaching a result through ordered steps: onboarding, check-in, an import, an end-of-day run. **Anatomy:** the step's form, a progress indicator (a bar, numbered steps, or a sticky side rail with a `current | total` counter), *Back* / *Next*, the completion action on the last input step, and a read-only result step. **Components you meet here:** `ProgressBar`, `ProgressSteps`, `Form`, `Notice`, and for long jobs the [long-running job](/ux-patterns/long-running-jobs/) progress. | Template | Archetype or piece | Detail | |---|---|---| | Step-by-step / guided process | `Wizard` + `@WizardProgress(STEPS \| RAIL)` | [Wizard](/ux-patterns/wizard/) | | Guided import | `ImportWizard<Row>` | [Guided import](/ux-patterns/guided-import/) | | A process inside a drawer | `Drawer` + an embedded wizard | [Guided process drawer](/ux-patterns/drawer/) | <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml # One definition per step (signup/1, signup/2…), each routed; Next navigates to the next step type: Form title: Sign up content: - {type: Text, text: "Step 1 of 3 — Your details", size: s} - {type: ProgressBar, value: 0.33} - type: FormLayout content: - {type: FormField, id: fullName, label: Full name, dataType: string, required: true} - {type: FormField, id: email, label: Email, dataType: string, stereotype: email, required: true} buttons: - {type: Button, label: Next, actionId: next, buttonStyle: primary} actions: - id: next steps: - {type: Navigate, route: signup/2} ``` </TabItem> <TabItem label="Java"> ```java @UI("/onboarding") @WizardProgress(WizardProgressStyle.STEPS) public class Onboarding extends Wizard { AccountTypeStep accountType = new AccountTypeStep(); // each step: a class implementing WizardStep CompanyStep company = new CompanyStep(); OnboardingResult result; // the last step: read-only result @WizardCompletionAction Object finish() { accounts.create(accountType, company); return null; } } ``` The `Wizard` archetype handles navigation, progress, cross-step state and branching (`stepApplies`). </TabItem> </Tabs> ![A wizard step with progress and Next](/images/docs/ux-patterns/wizard.png) ## Dashboard **For:** seeing at a glance what needs attention, and drilling in. **Anatomy:** a band of KPI cards (each optionally clickable), then a responsive grid of titled tiles (charts, short lists, notes). No form, no footer. **Components you meet here:** `Scoreboard`, `MetricCard`, `ResponsiveGrid`, `DashboardPanel`, `Chart`, `TrendChart`, `Stat`, `Meter`, `Funnel`, `Heatmap`. | Template | Archetype or piece | Detail | |---|---|---| | Dashboard | `Dashboard`, or a class of `MetricCard` fields with `@AutoPage` | [Dashboard](/ux-patterns/dashboard/) | <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml type: VerticalLayout content: - {type: Text, text: Sales, container: h2} - type: Scoreboard metrics: - {type: MetricCard, title: Revenue, value: "1.2M", unit: EUR, trend: up, trendLabel: +8% vs last month} - {type: MetricCard, title: Orders, value: "3,480", trend: up, trendLabel: +3%} - type: ResponsiveGrid columns: [{size: fill}, {size: fill}] content: - type: DashboardPanel title: Sales by region content: type: Chart chartType: bar chartData: labels: [May, Jun, Jul] datasets: [{label: North, data: [120, 135, 128]}, {label: South, data: [98, 104, 117]}] - type: DashboardPanel title: Latest orders content: type: Grid content: - {type: GridColumn, id: order, label: Order} - {type: GridColumn, id: total, label: Total, align: end} page: content: - {order: SO-1042, total: "1,250.00"} - {order: SO-1041, total: "860.50"} ``` </TabItem> <TabItem label="Java"> ```java @UI("/dashboard") @Title("Sales dashboard") public class SalesDashboard extends Dashboard { MetricCard revenue = MetricCard.builder() .title("Revenue").value("1.2").unit("M€") .trend(MetricTrend.up).trendLabel("+8% vs last month").build(); @Panel(title = "Notes") Markdown notes = new Markdown("- Summer campaign starts **July 15th**", null, null); } ``` Consecutive `MetricCard` fields form the KPI band; `@Panel` fields become tiles. </TabItem> </Tabs> ![A dashboard: KPI band and tiles](/images/docs/dashboard/sales-dashboard.png) ## Landing **For:** the front door of an app or a workflow: orientation and a few ways in. **Anatomy:** a hero (title, subtitle, optional image or tone) with calls to action, then highlight tiles; or a hero hosting a search with results as cards. **Components you meet here:** `HeroSection`, `Button`, `ResponsiveGrid`, `FeatureGrid`, `CalloutCard`, `Listing` as cards. | Template | Archetype or piece | Detail | |---|---|---| | Welcome | `Welcome`, or `@WelcomeBanner` on any page | [Welcome page](/ux-patterns/welcome-page/) | | Hero search | `HeroSearch<Filters, Row>` | [Hero search](/ux-patterns/hero-search/) | <Tabs syncKey="authoring"> <TabItem label="YAML"> ```yaml type: VerticalLayout content: - type: HeroSection title: Front desk subtitle: Everything you need, one click away. centered: true content: - {type: Button, label: Start check-in, actionId: startCheckin, buttonStyle: primary} - type: ResponsiveGrid columns: [{size: fill}, {size: fill}, {size: fill}] content: - {type: DashboardPanel, title: Arrivals, content: {type: Text, text: Today's arrivals.}} - {type: DashboardPanel, title: Departures, content: {type: Text, text: Today's departures.}} ``` </TabItem> <TabItem label="Java"> ```java @UI("/welcome") public class FrontDesk extends Welcome { Button start = Button.builder() .label("Start check-in").actionId("startCheckin") .buttonStyle(ButtonStyle.primary).build(); @Panel(title = "Arrivals") Markdown arrivals = new Markdown("Today's arrivals.", null, null); @Override protected String heroTitle() { return "Front desk"; } @Action Object startCheckin() { return URI.create("/checkin"); } } ``` </TabItem> </Tabs> ![A welcome page: hero with calls to action and tiles](/images/docs/welcome/welcome-demo.png) --- ## When no template fits The templates are a starting point, not a cage. Every archetype is a composition of ordinary components, so the same pieces compose freely in a page of your own (`ContentLayout`, `EntityHeader`, `HeroSection`, `TaskQueue`, `Card`…), and a page you compose still declares its type with `@PageTemplate` or `pageType:`. When even composition is not enough, see [Extending the UI](/ux/extending/). ## See also - [Choosing a page template](/ux-patterns/choosing-a-page-template/): the decision guide. - [Page templates](/ux-patterns/page-templates/): every template, its demo route, its Redwood status, and the shared header grammar. - [The Mateu Way](/the-mateu-way/): the six starting points in code, and the ladder of control. - [Layout inference](/ux-patterns/layout-inference/): what Mateu decides below the type. --- # How UX quality is kept URL: https://mateu.io/ux/quality/ > Why a Mateu app gets its UX quality without per-screen work, the principles behind every pattern, how they are checked, and what is guaranteed for accessibility and slow networks on every renderer. In a hand-built UI, quality is decided screen by screen. In Mateu it is decided **once**, in the derivation and in the renderers, and every app inherits it: a fix to how a rejected save is announced, or how a slow request is shown, reaches every screen of every app at the next release. That is also why your screens should stay inside the model as long as they can (see [extending the UI](/ux/extending/)): what you draw yourself, you have to get right yourself. ## The principles Every pattern exists to remove a concrete cost from people who spend their day in the app: preserve context, minimise navigation, keyboard first, workflow over screens, progressive complexity, recoverability and consistency. The [pattern catalogue](/ux-patterns/) lists them with the anti-pattern each one prevents (the CRUD tunnel, modal hell, filter amnesia…). ## How it is checked [How Mateu's UX is evaluated](/ux-patterns/how-ux-is-evaluated/) describes the method: heuristic reviews on every renderer in light and dark and at desktop and phone widths, cognitive walkthroughs of typical tasks, synthetic users with several profiles (first-time, keyboard-only, phone, screen reader), task metrics, and visual consistency rules. It also says plainly what those methods cannot replace. ## Accessibility Keyboard and screen-reader support is part of the renderers, not of your screens: labelled fields with their errors announced, focus moved to the first rejected field, dialogs and drawers that trap and return focus, a skip link, landmarks, live regions for navigation and messages, and keyboard activation for every clickable element. The same guarantees are expressed natively in React Native and IntelliJ, and probes check them on every change. - [Accessibility](/ux-patterns/accessibility/): what is guaranteed, per renderer, and how it is verified. - [Accessibility in your code](/java-user-manual/advanced/accessibility/): what remains yours (labels that make sense, alternatives for images, custom components). ## Slow and unreliable connections A business app is used on hotel Wi-Fi and in basements. The renderers show a skeleton when a page has no content yet, mark the pressed control as busy instead of freezing the screen, refuse double submits, retry safe reads, explain failures in plain language with a *Retry* control, and show when the connection is lost and when it is back. Writes are never repeated behind your back. See [slow connections](/ux-patterns/slow-connections/). ## Recoverability Mistakes are expected, so they are cheap: [undo](/ux-patterns/undo/) on reversible actions, confirmation on destructive ones, an unsaved-changes guard before leaving a dirty form, [conflict resolution](/ux-patterns/optimistic-locking/) when two people edit the same record, [session expiry](/ux-patterns/session-expiry/) that keeps the work, and an [error boundary](/java-user-manual/advanced/security/) that shows a readable message with a reference instead of a stack trace. ## Consistency across renderers and backends The same model must produce the same screen wherever it runs. The [renderer contract](/design-systems/renderer-contract/) measures each renderer against shared fixtures; the conformance corpus requires the Java, .NET and Python backends to produce identical wire output; and the [parity matrix](/reference/parity/) states what each one supports. More in [Quality](/quality/). --- # When to use Mateu URL: https://mateu.io/when-to-use-mateu/ Mateu is designed for **business applications**, not marketing sites. It shines when your UI is: - data-driven - CRUD-heavy - tightly coupled to backend logic However you start, the authoring surface is your choice: declare the model in **code** (Java, C# or Python) or in **YAML**, or draw it in the **visual editor**. And a Mateu app can be **served by a backend** or shipped as a **static bundle** to a CDN with no backend — so "needs a running backend" is not a prerequisite for adopting it. --- ## Ideal use cases ### Backoffice / admin panels - user management - permissions - configuration screens - internal tools 👉 If your UI is mostly forms and tables, Mateu is a very strong fit. --- ### Distributed backoffices (microservices) - multiple teams - bounded contexts - independent services Each service can define its own UI, and Mateu composes everything into a single application. 👉 This is one of Mateu’s biggest advantages. --- ### Embedded business modules - existing React / Vue apps - gradual adoption - hybrid architectures Mateu can be embedded as a web component: ```html <mateu-ui baseUrl="https://your-backend"></mateu-ui> ``` 👉 No need to rewrite your frontend. --- ## When Mateu is NOT a good fit Mateu is not designed for: - marketing websites - highly custom visual experiences - pixel-perfect design systems - frontend-heavy products (for example design tools or dashboards with very complex charts) In those cases, a traditional frontend stack is usually a better choice. --- ## Mental model Use Mateu when: > the UI is a projection of your backend model Avoid Mateu when: > the UI is the product itself --- ## Summary Mateu is a great choice for: - internal tools - admin panels - enterprise backoffices - UIs you want to define once and render on web, desktop and mobile — served by your backend or shipped as a static bundle --- ## Next - [Quickstart](/java-user-manual/start-here/quickstart/) - [Admin panel](/java-user-manual/use-cases/admin-panel/) - [Distributed backoffice](/java-user-manual/use-cases/distributed-backoffice/)

This is my app

The counter below is embedded from a remote Mateu app

This is my footer

; } ``` ## Vue example ```vue ``` The host framework does not need to know how Mateu renders the UI. It only needs to host the component. --- ## Why this is different from an iframe Mateu exposes a dedicated web component for rendering the UI. That means embedding feels like integrating a real frontend component, not just loading another page in a box. Conceptually: - iframe → external page - `mateu-ui` → embeddable UI component --- ## Mental model Mateu can act as: - a UI engine - a remote business module - an embeddable frontend component This is what makes it useful even in stacks that are already committed to another frontend framework. --- ## When to use this This pattern is especially useful for: - admin panels inside SaaS apps - internal tools inside existing products - gradual migration from React or Vue - teams that want backend-owned business modules --- ## Next - [Distributed backoffice](/java-user-manual/use-cases/distributed-backoffice/) - [Fluent components](/java-user-manual/concepts/fluent-components/) - [Build guides](/java-user-manual/build/) --- # Nested CRUD URL: https://mateu.io/java-user-manual/use-cases/nested-crud/ Manage hierarchical data within a single CRUD screen. This case shows how to embed nested editable collections inside a CRUD form, with each level having its own fields and nested children. --- ## What this case teaches - how to embed `List` fields in a CRUD form - how `@DetailFormCustomisation` controls how nested collections are edited - how `@Colspan` spans a field across multiple columns - how deeply nested structures (4 levels here) are handled the same way at each level - the Spring injection pattern for CRUD orchestrators with `store()` --- ## The structure This example manages entities with 4 levels of nesting: ``` Level1 (has many Level2) └── Level2 (has many Level3) └── Level3 (has many Level4) └── Level4 (leaf) ``` --- ## The models ### Level 1 (top-level entity) :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java @Style(StyleConstants.FULL_WIDTH_WITH_PADDING) public record Level1View( String id, String name, @Colspan(2) @DetailFormCustomisation(columns = 1, position = FormPosition.modal) List level2 ) implements Identifiable { @Override public String toString() { return id == null ? "New Level1" : name; } } ``` Key points: - `@Colspan(2)` makes the `level2` field span the full width when the form has 2 columns - `@DetailFormCustomisation(columns = 1, position = FormPosition.modal)` opens the detail editor for a Level2 item in a modal dialog with a 1-column layout - `implements Identifiable` is required for CRUD to work ### Level 2 ```java public record Level2View( String name, List level3 ) { @Override public String toString() { return name == null ? "New Level2" : name; } } ``` ### Level 3 ```java public record Level3View( String name, List level4 ) { @Override public String toString() { return name == null ? "New Level3" : name; } } ``` ### Level 4 (leaf) ```java public record Level4View( String name, int age ) { @Override public String toString() { return name == null ? "New Level4" : name; } } ``` Each level only needs to declare its fields and its children as a `List`. Mateu handles the rest. --- ## The infrastructure ### Repository ```java @Service public class Level1ViewStore implements CrudStore { // standard CRUD implementation @Override public Optional findById(String id) { ... } @Override public String save(Level1View entity) { ... } @Override public List findAll() { ... } @Override public void deleteAllById(List ids) { ... } } ``` ### Orchestrator ```java @Service @UI("/nested-crud") @RequiredArgsConstructor public class NestedCrud extends AutoCrud { final Level1ViewStore repo; @Override public CrudStore store() { return repo; } } ``` The orchestrator is registered at `/nested-crud` and uses the full Spring injection pattern. --- ## What `@DetailFormCustomisation` does ```java @DetailFormCustomisation(columns = 1, position = FormPosition.modal) List level2; ``` This annotation controls how Mateu renders the detail form when the user clicks on a row in the nested list. | Parameter | Effect | |-----------|--------| | `columns = 1` | The detail form uses 1 column layout | | `position = FormPosition.modal` | The detail form opens in a modal dialog | Without this annotation, the detail form opens inline below the list row, with the default column count. --- ## How nested collections are rendered By default, a `List` field renders as an editable inline table inside the form. Each row in the table shows the child's fields. Clicking a row opens the detail form (inline or modal, depending on `@DetailFormCustomisation`). Add/remove buttons are provided automatically. This applies at every level: Level2 shows inside Level1's form, Level3 shows inside Level2's form, and so on. --- ## Mental model - `List` in a form = editable nested collection - `@Colspan(2)` = spans full width in a 2-column layout - `@DetailFormCustomisation` = controls how the child detail editor opens - `FormPosition.modal` = opens in a dialog (useful when the child has many fields) - The top-level entity implements `Identifiable`; children do not need to - Nesting can go as deep as needed — each level follows the same pattern --- ## Next - [Distributed backoffice](/java-user-manual/use-cases/distributed-backoffice/) - [Master-detail (Process + Steps)](/java-user-manual/build/master-detail/) - [Relationships vs embedded CRUDs](/java-user-manual/build/relationships-vs-embedded-cruds/) --- # Users CRUD with lookups URL: https://mateu.io/java-user-manual/use-cases/users-crud/ Build a full CRUD for users, with role assignment via a lookup field, a custom editor page, and Spring dependency injection throughout. This case adds several real-world patterns on top of the basic CRUD: - Spring-managed beans for adapter and orchestrator - `@Lookup` for selecting values from a backend service - `@Stereotype` to render a multi-select as checkboxes - A separate editor page with its own route --- ## What this case teaches - how to use Spring injection in CRUD classes - how to define a lookup field backed by a backend service - how to add a custom editor page with a [`routes.yaml` entry](/concepts/routes-and-mounts/) - how actions return messages and refresh form state --- ## The pieces This case has five pieces: - `User` — the model - `UserStore` — the persistence layer - `UsersPage` — the CRUD orchestrator - `UserEditorPage` — a standalone editor bound to the CRUD - `RoleOptionsSupplier` / `RoleLabelSupplier` — lookup support --- ## 1. The model :::note[Imports] The samples leave out their `import` lines and compile with single-type imports. Some names exist in two Mateu packages (the `@Menu` annotation and the `Menu` record, `@Button` and `Button`…), so wildcard imports of both packages fail with "reference is ambiguous" — see [Java imports](/reference/java-imports/). ::: ```java public record User( @NotEmpty String id, @NotEmpty String name, @NotEmpty @Email String email, @Stereotype(FieldStereotype.checkbox) @Lookup(search = RoleOptionsSupplier.class, label = RoleLabelSupplier.class) List roles ) implements Identifiable { @Override public String toString() { return name != null ? name : "New user"; } } ``` Key points: - `@Lookup` tells Mateu where to find available options and how to display selected values - `@Stereotype(checkbox)` renders the field as a checkbox group, not a dropdown - `List` means the field holds multiple selected IDs --- ## 2. The repository ```java @Service public class UserStore implements CrudStore { private static final Map db = new HashMap<>(); static { db.put("1", new User("1", "Miguel", "miguel@example.com", List.of("1", "2"))); db.put("2", new User("2", "Ana", "ana@example.com", List.of("2"))); } @Override public Optional findById(String id) { return Optional.ofNullable(db.get(id)); } @Override public String save(User entity) { db.put(entity.id(), entity); return entity.id(); } @Override public List findAll() { return db.values().stream().toList(); } @Override public void deleteAllById(List selectedIds) { selectedIds.forEach(db::remove); } } ``` The repository is a `@Service` bean. This allows it to be injected wherever needed. --- ## 3. The orchestrator ```java @Service @UI("/users") public class UsersPage extends AutoCrud { final UserStore userStore; public UsersPage(UserStore userStore) { this.userStore = userStore; } @Override public CrudStore store() { return userStore; } } ``` `UsersPage` is a `@Service` bean. The repository is injected via constructor, and `store()` is the only method that needs to be overridden. Compare this to the Products example, where the repository was a plain class with no injection. In this case, `@Service` is required because the class holds an injected dependency. --- ## 4. The lookup support ### Options supplier ```java @Service public class RoleOptionsSupplier implements LookupOptionsSupplier { @Override public ListingData