Chapter 43 · Volume V — Reference

User Interface Extensions

Status: Informative · Platform version: 0.3.1 · Display label: ADL v0.3

Informative, not normative. Unlike the normative chapters, this chapter mandates no runtime behavior. It documents a design direction and how an external renderer may consume ADL; the Kalos backend generates no frontend code. It is included to record intent, not to define conformance.

This chapter describes how ADL carries user-interface intent — declarative hints an external rendering engine can consume to build an administrative interface. ADL describes backend data modeling, permissions, and behavior; the UI extensions let a schema additionally declare how a resource is intended to be presented. Kalos itself renders nothing: it stores these declarations and re-exports them on the schema endpoint, where a separate frontend maps them to concrete components.

43.1 Historical Context and Motivation

The User Interface Extensions were born out of a practical necessity: the need to rapidly build a fully functional Content Management System (CMS) without writing repetitive frontend code.

Initially, Kalos developers found themselves mirroring their robust ADL schema (which already contained deep knowledge about relationships, validation, and permissions) into frontend React components. This created a dual-schema problem. To solve this, ADL was expanded to act as a single source of truth not just for the database and API, but for the presentation layer as well. By embedding UI directives directly into ADL, a modern frontend can auto-generate the entire administrative interface dynamically.

43.2 Defining UI Elements in ADL

Rather than hard-coding frontend components, ADL allows developers to declare UI structures declaratively. A generic frontend client (such as a React SPA) reads a domain’s live schema from GET /api/v1/domains/{name}/schema and maps these ADL definitions to its own component library.

The elements that can be fully defined using ADL include:

  1. Navigations: Top-level sidebars, menus, and breadcrumbs mapped to specific Resource models.
  2. Forms and Dialogs: Auto-generating input fields based on ADL data types. For example, a string field might render as a standard text input, but a ui: { widget: "markdown" } directive will seamlessly render a rich-text Markdown editor.
  3. Popups & Modals: Confirmations for destructive actions or multi-step wizards for complex data entry.
  4. Interactive Dashboards: Custom layouts that aggregate data across multiple resources.
  5. Charts and Diagrams: Visualizing metrics or relationships declaratively via the ui configuration blocks.

43.3 Seamless Integration with Existing ADL Features

User Interface Extensions integrate with Kalos’s backend features. Because the UI intent is derived from the ADL schema, a renderer inherits those capabilities without extra frontend wiring:

  • RBAC (Role-Based Access Control): If a user’s role lacks the update permission for a specific field, the frontend will automatically render that input as disabled or hide it entirely.
  • State Machines: Transitions defined in the ADL state machine automatically generate context-aware action buttons (e.g., rendering an “Approve” button only if the document is in the “Draft” state).
  • Workflows: Multi-stage background processes seamlessly surface progress bars and status indicators in the generated UI.
  • Media Manager: Fields of type media automatically render file upload zones with the correct size restrictions, MIME type limits, and image previews.
  • History of Changes & Audits: ADL’s native audit trail automatically maps to frontend “Revision History” side panels, allowing users to view diffs and revert changes.
  • Sheets Mode: Resources configured for bulk editing can be presented as spreadsheet-like grid views, applying ADL’s compositePrimaryKey and validation rules on every cell edit.

43.4 Architecture: The Frontend Consumer

It is important to note that the Kalos backend does not generate HTML or JavaScript. Instead, ADL defines the intent of the interface.

The frontend acts as a rendering engine—typically built using React—that consumes the ADL schema JSON. It maps the schema’s abstract definitions (like widget: "datetime") to concrete React components. This separation of concerns keeps the Kalos backend lightweight and API-driven, while letting developers define the intended interface declaratively.