major
#29596
TL Views: Design Options for App-Specific Interfaces (CSS classes, text variations, layout options, input display variations, theme tokens)
Context
A gap analysis of the real estate application (estate-agent, hand-coded React front end with a dark “glass” design, serif headings, photo tile grids, a filter sidebar with chips, segment switches, and sliders) against the React interface (.view.xml level) has revealed: The structure (app shell, navigation, routing, tables, forms, dialogs, charts, theme system with dark mode) is in place, but an app-specific appearance cannot be implemented because the elements lack style anchors and have only a basic layout vocabulary.
The theme itself (colors, fonts, icon sets) remains app-specific and is configured within the application. The engine ticket only provides the options and tokens that are missing for this purpose. Principle: Options on existing elements instead of new elements.
Extension
The ticket will be implemented in phases on a branch (multiple pushes/CI runs).
Phase 1: `css-class` for all elements
UIElement.Config gains the `css-class` property, which each control writes to its root element. The existing property of the same name on `<text> ` is moved to the base configuration; `<chart cssClass> ` is updated accordingly. This allows an app stylesheet rule (registered via ClientResources) to style individual panels, cards, stacks, images, or buttons (“this particular card is a glass card”).
Phase 2: Text Variations, Sound, and Pill
<text> receives
- variant (type role): display, headline, title, body (default), label, caption;
- tone (color role): primary (default), secondary, helper, accent, success, warning, error, on-color;
- appearance: text (default) or pill (existing TLPill representation; color from tone).
Each variant is rendered as a stable CSS class (tlText--display, tlText--tone-accent, …) and populated from theme tokens.
New theme tokens with neutral default values that the controls consume, so that an app theme can override them:
- font-family-display (font for display/`headline`/`title`; default = font-family),
- border-radius-03 (third radius level for large areas),
- surface-blur (backdrop blur for areas; default 0),
- shadow-glow (glow shadow for focus/highlighting; default = no shadow),
- background-image (app shell background; default = none).
Transparent areas, grain, secondary accents, and similar elements remain in the app stylesheet.
Phase 3: Layout Options
- <stack>: wrap, justify, and max-width (centered content column).
- <grid>: max-width. (max-columns as the upper limit for auto-fit, e.g., 3 cards per row, provided by #29597 via the shared grid options of <grid> and <object-list layout="grid">.)
Hero sections with background images and overlays are implemented via app CSS on a CSS class stack; no engine element is required for this.
Phase 4: Display Variants for Input Fields
The field control providers receive a ` display` option, which is set via an `<input-control>` annotation on the attribute or on the `<field> ` element:
- SelectControlProvider: dropdown (default), chips (multiple selection as a tag cloud with toggleable chips), segmented (single selection as segmented radio buttons with a sliding marker);
- NumberInputControlProvider: input (default), slider (with min, max, step, and displayed value);
- BooleanControlProvider: checkbox (default), switch.
<value-input> accepts the same options.
Phase 5: `<value-input>` as a search field
<value-input> now supports `icon`, `placeholder`, `clearable `, and `debounce ` (delay before the value is written to the channel), allowing a standalone search field with a magnifying glass to be configured without its own element (along with the existing `on-submit ` and `<query-bindings>`). (placeholder is already included in #29608.)
Phase 6: Transition anchors
Opening/closing dialogs and frame changes in the tile-stack will receive CSS-transition-enabled state classes, allowing app CSS to define fade-in/fade-out effects. `prefers-reduced-motion` will continue to be honored. The animations themselves remain the responsibility of app CSS.
Solution
Implemented in two pushes on the same branch: Phases 1, 2, 3, and 5, followed by Phases 4 and 6.
Phase 1
`UIElement.Config#getCssClass() ` (css-class) is the single configuration property for all elements. On the control side, there is exactly one state key, ` cssClass `, in the base class `ReactControl ` (`setCssClass`, included in `scriptingPresentationKeys()`; subclasses supplement their keys via presentationKeys(super.scriptingPresentationKeys(), …)); the previous individual keys of the same name from ReactTextControl, ReactHtmlControl, ReactImageControl, ReactStackControl, ReactOverlayControl, and ReactResourceCellControl are no longer used. Each of the 66 elements passes its configured class to the returned Control (there is no central creation point; child Controls are mounted on the client side without a wrapper element). An element that passes on another element’s control (such as `view` or `tile`) only sets the class if it has configured one itself. On the client side, the bridge function `rootClassName(state, …)` constructs the `className` of the root element for each of the 78 registered components. <text> sends its overflow modifier as its own state key `overflow` instead of in the class string; the `TextOverflow ` enum is associated with the control. The differently named `cssClass ` property of `<chart> ` is omitted; the inherited ` css-class` applies. FAQ: docs/faq/react-view-layer.md (section “Styling a single element”), docs/faq/new-ui-element.md.
Phase 2
variant, tone, and appearance are three ExternallyNamed enums(TextVariant, TextTone, TextAppearance in com.top_logic.layout.react.control.common) on TextElement.These are passed as separate state keys to TLText (default values are included) and become tlText--<variant>, tlText--tone-<tone>, and tlText--pill there. Each tone is a rule that populates the custom property --tlText-tone; they read the text color and pill color. appearance="text" retains the current behavior (a value with a model color is displayed as a pill); appearance="pill" always renders a pill whose color comes from tone, provided the value does not have a model color; text without content does not draw a pill. The recoloring of text in the primary app bar now only uses ` tlText--tone-primary`, so an explicitly set tone takes precedence there.
Typography: `display ` and `headline` receive their own tokens (`display-01-font-size/`-line-height`, ` heading-04-font-size/`-line-height`) and `font-family-display`; title = heading-03 (+ new heading-03-line-height), body = body-compact-01, label = heading-compact-02, caption = label-01 (+ new label-01-line-height). Sounds: primary/`secondary`/`helper`/`on-color`/`error` use the existing text-* tokens; new as ref tokens : text-accent → interactive, text-success → support-success, text-warning → support-warning.
Additional tokens in the default theme(inherited by Dark): font-family-display (refers to font-family), border-radius-03 (1rem, third radius level “large area”; docs/faq/react-theme-tokens.md describes three levels), surface-blur (length, 0`; consumed by the dialog backdrop), `shadow-glow` (text, none), background-image (text, none; consumed by ` body ` in `tlReactBase.css `).
Phase 3
<stack>: wrap (boolean), justify (enum ReactStackControl.StackJustify: start, center, end, space-between, space-around, space-evenly, rules .tlStack--justify-*) and max-width. `max-width` is derived from the common base class `ReactLayoutControl ` (state key `maxWidth`, class `tlBounded`: `width: 100%`, `margin-inline: auto`) and, for grids, from the common `GridOptions`; it therefore applies to `<grid> ` and `<object-list> ` (grid and list layouts). As with `<panel width>`, the type is a CSS length value as a string. The stack’s layout keys are declared as pure presentation in the headless projection. See the FAQ section “Layout: stack and grid.”
Phase 4
The display variants are options of the existing field control providers (com.top_logic.layout.view.form), set via the existing <input-control> mechanism: as a TLInputControl annotation on the attribute or type, as the input-control of a <field>, and—new—as the input-control of a <value-input> (ValueInputElement.Config; the type-based path of FieldControlService.createFieldControl takes a provider configuration as a priority parameter for this). Each variant is a pure display state key (display, declared in scriptingPresentationKeys() ), so that the headless projection reads the same options and the same value in every form.
- Switch: BooleanPresentation (model annotation <boolean-display presentation="switch"/>) takes the value "switch"; the classic UI treats it as a checkbox (CheckboxInputTag, PrimitiveColumn, AttributeOperations). BooleanControlProvider.Config#display (@NullDefault) overrides the annotation for a field. ReactCheckboxControl sends display=switch; TLCheckbox renders <input type=checkbox role=switch class="tlReactCheckbox--switch"> with a track and button from theme tokens. A tristate value remains a checkbox (a switch has no third state).
- Chips / Segments: SelectControlProvider.Config#display with Enum SelectDisplay (dropdown, chips, segmented; com.top_logic.layout.react.control.select). A server-side control, ReactDropdownSelectControl, maintains the option index and value history for all forms and selects the appropriate React module (TLDropdownSelect, TLOptionChips, TLSegmentedChoice); a form that displays all options receives the option list immediately and upon every value change (invalidateOptions()), while the dropdown continues to load only when opened. Client: selectOptions.tsx (shared option descriptor, pill, image, read-only value), TLOptionChips (toggle buttons with ` aria-pressed`; single selection toggles, multiple selection switches), TLSegmentedChoice (radiogroup/`radio` with arrow keys, sliding marker via ResizeObserver; for multiple selection, filled segments without a marker).
- Sliders: ` NumberInputControlProvider.Config ` with `display ` (enum `NumberDisplay`: `input`, `slider`), `min`, `max`, `step`. Validation is enforced by configuration constraints, ensuring that a configuration form does not allow invalid configurations: min/`max` are required as soon as display="slider" (new general annotation @MandatoryIf(other=@Ref(DISPLAY), value="slider") in com.top_logic.basic.config.constraint.annotation, which compares the configuration notation of the other value), min < max (@ComparisonDependency), step > 0 (@Bound). Custom ReactSliderControl ( TLSlider module): the value is exchanged as a number (not as text in locale format) and converted to the field’s number type via ` NumberFormats.normalize `; the server renders the label next to the slider handle (valueLabel) in the field’s format. Client : `<input type=range> ` + `<output>`, debounced submission and submission on release.
Tests: TestBooleanControlProvider, TestSelectControlProvider, TestNumberInputControlProvider (including constraint cases), TestMandatoryIf, TestValueInputElement. FAQ: docs/faq/react-view-layer.md, section “Display variants of input fields.”
Phase 5
icon (encoded ThemeImage, e.g., css:fa-solid fa-magnifying-glass), clearable, and debounce are applied to each field control in ReactFieldControlProvider.createField, similar to placeholder (#29608) FieldSpec properties applied to each field control in ` ReactFieldControlProvider.createField `; sent to the client as state keys `icon`, `clearable`, and `debounceMs ` from `ReactFormFieldControl ` (pure presentation; placeholder remains in the projection) and implemented in TLTextInput: leading icon, clear button (appears only when content is present, immediately sets the empty value, returns focus to the field), configurable delay. The constant VALUE_DEBOUNCE_MS (300 ms) is defined once in the bridge; text, number, and password fields read debounceMs. A field that submits only when exited (URL field, number) ignores the delay. <value-input> declares icon, clearable, debounce (@Format(MillisFormat.class), e.g., debounce="300ms").
Phase 6
A Bridge hook `useKeyedTransition({keys, node, container, enterClass, exitClass}) ` (react-src/bridge/transition.ts, exported from tl-react-bridge) marks the change in what a control displays: a newly appearing key is assigned the `enter` class on its element; a disappearing key is replaced in the container by an inert copy of its last-displayed element (aria-hidden, inert, no IDs, pointer-events: none) with the `exit` class. Both end with an animation/`transition` on the element itself, upon the key’s reappearance, or after TRANSITION_FALLBACK_MS (1000 ms, once defined). The initial display—and, regardless of the app’s CSS, a viewer with `prefers-reduced-motion: reduce `—receives neither a class nor a copy.
Consumers and classes:
- Wizard: tlWizard__step--entering / tlWizard__step--exiting, tlWizard--forward|backward; retains its default animation. The previous inline code copied the step after the DOM swap and thus captured the incoming step instead of the exited one (confirmed in the browser); the hook remembers the element of each key after every commit and copies the one that was actually exited.
- Dialog: tlDialog__backdrop--entering on the backdrop of the open dialog, tlDialog__backdrop--exiting on the copy of the closed dialog (the TLDialogManager is the container and therefore remains rendered even without dialogs). The copy covers the page and allows all input to pass through.
- Tile Stack: tlTileStack__frame--entering / tlTileStack__frame--exiting and tlTileStack--forward|backward (derived from the change in activeIndex ).
For dialogs and tile stacks, the engine provides only the structural rules for the copy (position: absolute; inset: 0; pointer-events: none or pointer-events: none), not any animation. FAQ: “Transitions” section in docs/faq/react-view-layer.md.
Demo
com.top_logic.demo.react: “Design” page (demo/styling-demo.view.xml) with all text variations and colors, pills made of clay and model paint, hero banner and glass card via CSS class from tl-demo-react.css, stack/grid options, search field, and the “Input Display Variations” section (form via a transient demo.react:demo with chips, segments, sliders, and toggles, plus `<value-input>`s with `input-control`). tl-demo-react.css animates the transition classes (dialog fades in/out, tile stack frames slide depending on direction). Additional demo theme “glass” (extends “default”), which sets ` surface-blur`, ` shadow-glow `, and ` font-family-display `.
Not included in this ticket: generic repeater (object-list), image extension, wizard/stepper, display of long-running jobs, and display of HTML documents/printing. There are separate tickets for these.