App Annotations

@UI

Target: TYPE

The primary annotation. Registers a class as a UI endpoint and mounts it at the given route path. Every Mateu application needs at least one @UI-annotated class.

public @interface UI {
    String value();                                         // required: route path e.g. "/orders"
    String indexHtmlPath() default "/static/_index.html";
    String frontendComponentPath() default "/assets/mateu.js";
}

Attribute	Type	Default	Description
value	String	—	URL path at which this UI is mounted
indexHtmlPath	String	"/static/_index.html"	Path to the HTML shell served for this UI
frontendComponentPath	String	"/assets/mateu.js"	Path to the compiled frontend component

@UI("/home")
@Title("My first Mateu app")
public class Home {

    @NotEmpty
    String name;

    @Button
    public Message greet() {
        return new Message("Hello " + name);
    }
}

---

@App

Marks a class as the application shell and selects its navigation layout variant.

public @interface App {
    AppVariant value();
}

Attribute	Type	Description
value	AppVariant	Layout variant for the application shell

AppVariant values:

Value	Description
HAMBURGUER_MENU	Collapsible hamburger-style navigation drawer
MENU_ON_LEFT	Persistent navigation panel on the left side
MENU_ON_TOP	Navigation bar along the top
TABS	Tab-based navigation
AUTO	Framework chooses the best variant automatically
MEDIATOR	Used for nested sub-applications acting as a mediator

@UI("/app")
@App(AppVariant.HAMBURGUER_MENU)
public class ShellApp implements App { ... }

---

@PageTitle

Target: TYPE

Sets the browser tab title (<title> element in the HTML).

public @interface PageTitle {
    String value();
}

@UI("/orders")
@PageTitle("Orders – My App")
public class OrdersPage { ... }

---

@Title

Target: TYPE

Sets the visible heading rendered inside the page, above the content area.

public @interface Title {
    String value();
}

@UI("/home")
@Title("My first Mateu app")
public class Home { ... }

@Title controls the heading inside the page UI. @PageTitle controls the browser tab. Both can be combined.

---

@Subtitle

Target: TYPE

Sets a subtitle displayed below the page title.

public @interface Subtitle {
    String value();
}

@UI("/products")
@Title("Product Catalog")
@Subtitle("Browse and manage all products")
public class ProductCatalog { ... }

---

@Logo

Target: TYPE

Sets the URL of the image displayed as the application logo in the header or navigation drawer.

public @interface Logo {
    String value();  // URL or path to the logo image
}

@UI("/_workflow")
@Logo("/images/logo.svg")
public class WorkflowHome { ... }

---

@FavIcon

Target: TYPE

Sets the browser favicon for the UI.

public @interface FavIcon {
    String value();  // URL or path to the favicon
}

@UI("/_workflow")
@FavIcon("/images/favicon.ico")
public class WorkflowHome { ... }

---

@DrawerClosed

Target: TYPE

No attributes. Starts the navigation drawer in the closed (collapsed) state when the page is first loaded.

@UI("/app")
@App(AppVariant.HAMBURGUER_MENU)
@DrawerClosed
public class ShellApp implements App { ... }

---

@KeycloakSecured

Target: TYPE

Integrates Keycloak authentication. The frontend will redirect unauthenticated users to the Keycloak login page before the UI is displayed.

public @interface KeycloakSecured {
    String url();
    String realm();
    String clientId();
    String jsUrl() default "";
}

Attribute	Type	Default	Description
url	String	—	Keycloak server base URL
realm	String	—	Keycloak realm name
clientId	String	—	Keycloak client ID
jsUrl	String	""	Optional override for the Keycloak JS adapter URL

@UI("/_workflow")
@KeycloakSecured(
    url    = "https://auth.example.com",
    realm  = "myrealm",
    clientId = "my-app"
)
public class WorkflowHome { ... }

---

@UISpec

Target: TYPE

Points to a YAML file that describes the UI declaratively instead of (or alongside) Java annotations.

public @interface UISpec {
    String value();  // path to a YAML UI spec file
}

@UI("/dashboard")
@UISpec("/specs/dashboard.yaml")
public class Dashboard { ... }

---

@AI

Target: TYPE

Enables an AI assistant sidebar for the UI by wiring it to a Server-Sent Events (SSE) endpoint that streams AI responses.

public @interface AI {
    String sse();  // SSE endpoint for AI assistant streaming
}

Attribute	Type	Description
sse	String	Path to the SSE endpoint that provides AI responses

@UI("/support")
@AI(sse = "/api/ai/stream")
public class SupportPage { ... }

---

Combined example

@UI("/home")
@Title("My first Mateu app")
@Style(StyleConstants.CONTAINER)
public class Home {

    @NotEmpty
    String name;

    @Button
    public Message greet() {
        return new Message("Hello " + name);
    }
}

A full application shell combining several annotations:

@UI("/_workflow")
@FavIcon("/images/favicon.svg")
@PageTitle("Workflow Engine")
@Logo("/images/logo.svg")
@Title("Workflow Engine")
@KeycloakSecured(url = "https://auth.example.com", realm = "myrealm", clientId = "workflow")
public class WorkflowHome {

    @Menu
    WorkflowMenu workflow;
}