# Migrating a TopLogic application from 8.0.0-alpha8 to 8.0.0-alpha9

Audience: an AI coding agent (or developer) upgrading a TopLogic application project.
Sources: release notes https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha9/ and the
TopLogic Trac tickets flagged `RequiresMigration` for milestone `TL_8.0.0-alpha9` (ticket numbers
are given as `#NNNNN`; the per-ticket page is `https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha9/NNNNN/`).

This release renames the CSS classes of the classic controls to BEM names (#28474), introduces the
design system of the React view layer (#29617), changes several elements of the React view files
(`*.view.xml`: #29502, #29597, #29611, #29663), makes access grants additive (#29564), removes the
`use-default-security-parent` option (#29678), makes `SecurityObjectByExpression` actually check
access (#29508) and lets composition parts follow the access decision of their container (#29637).
React views must be registered as entry points to be opened by URL (#29551), and the build requires
Maven 3.8.9 (#29702). Several engine migration scripts rewrite data automatically (#29512, #29540,
#29548, #29563, #29590).

## How to use this document

1. Work through the sections in order. Section 1 must be done first (the project does not build
   otherwise); the rest can be done in any order.
2. Every step has a **Detect** line: run the search in the application's source tree. If it finds
   nothing, the step does not apply — skip it. Do not invent changes for steps that do not apply.
3. Many changes are reported as **configuration errors at application start or when a view is
   loaded** (not at compile time). After migrating, start the application, log in — as an
   administrator **and** as a regular (non-admin) user — and open every view; read the log for
   `ConfigurationException` / configuration errors.
4. Some changes only show at run time or visually (lost styling, changed spacing, views that are
   no longer accessible). They are marked **review**: check the described code, do not change it
   blindly.
5. The engine ships developer articles in its jars (`META-INF/tl-docs/**/*.md`). If the `tl-mcp`
   tools are available, read them with `read_doc`.
6. Ticket descriptions on Trac are partly German; this document translates the instructions.

Search commands below assume the project root as working directory and GNU grep.

---

## 1. Build and platform

### 1.1 Version bump
Set the TopLogic version to `8.0.0-alpha9` (parent `tl-parent-app` / `tl-parent-core` version, or
the `tl.version` property).

Detect: `grep -rn --include=pom.xml -e '8.0.0-alpha8' .`

### 1.2 Maven 3.8.9 or newer (#29702) — mandatory
Applications inherit the `maven-enforcer-plugin` rule `requireMavenVersion` from `tl-parent-all`;
it now requires Maven **3.8.9** (before: 3.6.0). With an older Maven the build stops right at the
start. Build environments and CI must use Maven 3.8.9 or newer. Report the required version to the
user if the CI configuration is outside the source tree.

Detect: `mvn -v | head -1`; `grep -rn -i -e 'maven' .mvn/wrapper/maven-wrapper.properties Jenkinsfile .gitlab-ci.yml .github/workflows 2>/dev/null`

### 1.3 Generated React bundles are no longer committed (#29547) — only when building engine React modules from source
The JavaScript bundles generated by Vite under `src/main/webapp/script/` of the engine's React
modules (e.g. `tl-react-bridge.js`, `tl-react-controls.js`, `tl-react-chartjs.js`,
`tl-code-editor.js`, `tl-react-wysiwyg.js`, `tl-script-editor.js`, `tl-react-flow-controls.js`) are
no longer in the repository; the build still creates them (phase `generate-resources`) and the jars
contain them as before. An application consuming the engine jars needs no change. Only a workspace
that builds the React modules from source outside Eclipse must build them once with `mvn compile`
after a checkout or branch switch (in Eclipse, m2e builds them).

Detect: `find . -path ./target -prune -o -name 'package.json' -path '*react*' -print`

### 1.4 Java API changes — mandatory if used (Java)
Compile errors point to these; the list says what to do. Each item names its ticket.

**Model, security and TL-Script**

- **Own TL-Script functions (#29555) — review.** A `GenericMethod` subclass that reads data not
  given in its arguments (session locale, current user, time zone, request state) must override
  `canEvaluateAtCompileTime(Object[])` and return `false`. Otherwise constant folding evaluates a
  call with constant arguments once at compile time and freezes the result for every user. This is
  not a compile error.
- **`@SideEffectFree` is evaluated (#29645) — review.** The annotation on TL-Script functions
  defined as static methods of `TLScriptFunctions` classes had no runtime retention and was
  ignored; now it is evaluated, so the compiler may reorder, drop or duplicate calls. Methods with
  side effects must not carry it — remove the annotation there.
- **Default group (#29563).** `Group#setDefaultGroup(boolean)` and `Group.GROUP_DEFAULT` are gone.
  Remove the calls: the default group is defined only by `default-group` of the
  `InitialGroupManager` configuration (section 2.4).
- **Access grants (#29564).** `AccessRightsConfig#getGrants()` returns a `List<AccessRule>` instead
  of a map keyed by `CommandGroupReference`.
- **Association storages (#29681).** `AssociationStorageDescriptor` has the new abstract method
  `getBaseObjectColumn()` (name of the reference that holds the base object of a row); own
  implementations must implement it. `DefaultAssociationStorageDescriptor#baseObjectCol()` is now
  `getBaseObjectColumn()`.

**React view layer** (only applications with own Java code for the React UI)

- **Field control providers (#29429).** `com.top_logic.layout.view.form.ReactFieldControlProvider`
  → `com.top_logic.layout.react.field.ReactFieldControlProvider`. The method receives a `FieldSpec`
  describing the edited value instead of the model attribute. A provider registered for a model type
  through `FieldControlService` needs no change.
- **Designer selectors (#29429).** An own `UIElement`, `ReactCommand` or `ViewAction` that should be
  offered in the view designer's selectors must carry `@InApp`; without it, it remains configurable
  but is no longer listed.
- **Command models (#29679).** An own `com.top_logic.layout.react.control.button.CommandModel`
  implements `perform(ReactContext)` instead of `executeCommand(ReactContext)` (rename the method;
  `executeCommand` checks the executability and must not be overridden any more). An own
  `UploadCommandModel` implements `uploadFiles(...)` (returns a `HandlerResult`) instead of
  `upload(...)`. The select handler of `ReactMenuControl` (constructor, `setSelectHandler`) is a
  `Function<String, HandlerResult>` instead of a `Consumer<String>`; the submit listener of
  `ReactFormFieldControl` a `Function<Object, HandlerResult>`.
- **Menus (#29525, #29540, #29679).**
  - Renamed:

    | before | now |
    |---|---|
    | `com.top_logic.layout.view.command.ContextMenuRegionControl` | `com.top_logic.layout.view.command.MenuRegionControl` |
    | React module `TLContextMenuRegion` | `TLMenuRegion` |
    | `ContextMenuElement.DEFAULT_TARGET_CHANNEL` | `AbstractMenuElement.DEFAULT_TARGET_CHANNEL` |

    `MenuRegionControl` takes a list of `ContextMenuContribution`s instead of a single one, and a
    `MenuTrigger`. The `<context-menu>` element and its configuration are unchanged.
  - `ReactMenuControl.MenuEntry` gained the components `cssClasses` (#29525) and `active` (#29540)
    and carries an `ExecutableState` instead of the flag `disabled` (#29679). Build entries with the
    `item(...)` / `separator()` factories instead of the canonical constructor; code using the
    five-argument `item(...)` passes the `active` flag.
  - `ContextMenuContribution` gained a three-argument constructor (the two-argument one is
    unchanged); `CommandModel` gained `isActive()` with default `false` (no change needed).
- **Other constructors (#29525, #29502).** `UITheme` gained an `icon` constructor parameter;
  `ReactAppBarControl` gained a trailing control parameter (the shorter constructors are unchanged).
  `ObservableTreeModel` takes the parents function as an additional constructor argument.
- **Themes (#29528).** `UIThemeService.getActiveThemeId()` / `setActiveThemeId(String)` are replaced
  by `getSelectedThemeId()` (returns `null` for "no choice stored", never the default) and
  `setSelectedThemeId(String)` (`null` clears). Code that needs the theme in effect on the client
  reads `document.documentElement.dataset.theme`.
- **Buttons (#29617).** `ButtonSize.LARGE` no longer exists; use the default size.
  `ButtonAppearance.LINK` combined with `ButtonTone.DANGER` is not supported (the tone is ignored for
  links).
- **Form insets (#29663).** Java code creating a `ReactFormLayoutControl` (e.g. via
  `ReactFormBuilder`) for a dialog body wraps it in a `ReactInsetControl` (forms no longer pad
  themselves, see 4.4).
Detect:
```
grep -rn --include=*.java -e 'extends GenericMethod' -e 'SideEffectFree' -e 'setDefaultGroup' -e 'GROUP_DEFAULT' -e 'getGrants()' \
  -e 'AssociationStorageDescriptor' -e 'baseObjectCol' .
grep -rn --include=*.java --include=*.ts --include=*.tsx -e 'ReactFieldControlProvider' -e 'implements UIElement' \
  -e 'ReactCommand' -e 'ViewAction' -e 'CommandModel' -e 'ReactMenuControl' -e 'MenuEntry' -e 'ReactFormFieldControl' \
  -e 'ContextMenuRegionControl' -e 'TLContextMenuRegion' -e 'DEFAULT_TARGET_CHANNEL' \
  -e 'ContextMenuContribution' -e 'new UITheme' -e 'ReactAppBarControl' -e 'ObservableTreeModel' \
  -e 'ActiveThemeId' -e 'ButtonSize.LARGE' -e 'ButtonTone.DANGER' -e 'ReactFormLayoutControl' -e 'ReactFormBuilder' .
```

---

## 2. Server configuration, model and database

### 2.1 `use-default-security-parent` removed (#29678) — mandatory if used
The option `use-default-security-parent` of the `BoundHelper` configuration is gone; an application
setting it fails to start with a configuration error (unknown property). Without a configured
security parent rule an object has no security parent. Remove the attribute and, for every type
whose instances should inherit roles from the security root, add a security-parent rule pointing to
the root (once with `inherit="true"` on a common super type):

```xml
<config service-class="com.top_logic.tool.boundsec.manager.AccessManager">
	<instance>
		<security-parents>
			<rule id="SecRootForProject" inherit="true" meta-element="myapp:Project">
				<singleton module="SecurityStructure"/>
			</rule>
		</security-parents>
	</instance>
</config>
```

Applications that did not set the option are not affected.

Detect: `grep -rn 'use-default-security-parent' --include=*.xml .`

### 2.2 Access grants are additive (#29564) — review
A `<grant>` of the application for an operation that a framework module already grants on the same
type used to replace the framework's roles. Grants are now additive: the application keeps the
framework's roles in addition to its own. To remove a framework role, add a revoke in the
application configuration; to replace the whole rule sequence of a type, put
`config:override="true"` on the `<class>` element:

```xml
<class name="tl.accounts:Person">
	<revoke operation="Read" roles="..."/>
</class>
```

Detect: `grep -rn -e '<grant' --include=*.xml src/main/webapp/WEB-INF` — for each `<class>` with a
grant, check whether the framework grants the same operation on that type (engine
`*SecurityConfigurationService*` / `*.config.xml` files) and whether the additional framework roles
are acceptable.

### 2.3 Country resource provider removed from `tl-contact` (#29525) — mandatory if used
`com.top_logic.contact.layout.CountryResourceProvider` is gone, together with its two registrations
in `contactConf.config.xml`. A country is served by `com.top_logic.util.CountryResourceProvider`,
registered in `top-logic.config.xml`, which produces the same label and adds the flag. Drop
references to the removed class; an application that registered it for an own type names the new
class instead.

Detect: `grep -rn 'contact.layout.CountryResourceProvider' .`

### 2.4 Default group is derived from the configuration (#29563) — no manual steps (data-touching)
The model migration `Ticket_29563_default_group_derived` (module `tl-element`) deletes the persistent
attribute `tl.accounts:Group#defaultGroup` including its flex data in table `Group` and creates it
anew as a derived attribute. The default group is defined exclusively by `default-group` of the
`InitialGroupManager` (Java API: section 1.4).

The migration of #29447 (removing the anonymous account from the default group, alpha8) now requires
a configured `default-group` that names this group at the time of the migration; without a
configured default group it removes nothing.

Detect: `grep -rn -e 'default-group' -e 'defaultGroup' --include=*.xml --include=*.java .`

### 2.5 Framework datatypes `tl.util:EMail` and `tl.util:Phone` (#29548) — mandatory on name collision
The datatypes `tl.util:EMail` and `tl.util:Phone` are created in existing databases by the automatic
migration `Ticket_29548_create_email_phone` (module `tl-element`). An application that already
defines a type named `EMail` or `Phone` in the module `tl.util` collides with them and must rename or
drop its own definition before the update.

Detect: `grep -rln -e 'tl.util' --include=*.model.xml . | xargs -r grep -n -E 'name="(EMail|Phone)"'`

### 2.6 Automatic model and data migrations (#29512, #29540, #29590) — no manual steps
- `Ticket_29512_mandatory_model_attributes` (`tl-element`) sets the `mandatory` flag of attributes
  of `tl.model` that are mandatory de facto and adjusts the model baseline. Database schemas are
  unchanged.
- `Ticket_29540_mandatory_timezone` (`tl-element`) makes `tl.accounts:Person#timezone` mandatory;
  the attribute has a default value, so no account is left without one. Code that sets the timezone
  of an account to `null` now fails validation (Detect:
  `grep -rn --include=*.java --include=*.xml -i 'timezone' . | grep -i -e 'null' -e 'setValue'`).
- `Ticket_29590_multi_valued_datatypes` (`tl-element`) adds `<supports-multiple/>` to the datatypes
  `tl.core:Boolean`, `Date`, `Day`, `Time` and `DateTime`. Existing lists of numbers, booleans and
  strings are read unchanged.

Own migration scripts that touch these types should depend on the engine scripts.

---

## 3. Security / access checks

### 3.1 `SecurityObjectByExpression` checks access (#29508) — review
**Views can become inaccessible after the upgrade.** So far a `SecurityObjectByExpression` returned
`null` when its expression computed an object the user may not see; the view or command was then
treated as a technical view without security and was visible to everybody. Now the security object is
delivered correctly and the permission is actually checked. Views that were (unintentionally) open
to everybody are reachable only with a matching role assignment afterwards.

- Check the role assignments on the affected security objects. Rights are granted in the role
  profile administration (Administration › role profiles); if the application ships a
  `security.xml`, adjust it there as well.
- Optional: where the expression only returns a singleton, use the
  `ModuleSingletonSecurityProvider` instead:
  ```xml
  <securityObject class="com.top_logic.tool.boundsec.securityObjectProvider.ModuleSingletonSecurityProvider"
  	module="MyModule"
  />
  ```
  This denotes `MyModule#ROOT`; for another singleton set the attribute `singleton-name`.

Detect: `grep -rn -e 'SecurityObjectByExpression' -e 'security-object-by-expression' --include=*.xml .`
Report the affected views to the user; test them as a regular user.

### 3.2 Composition parts follow the access decision of their container (#29637) — review
Objects of types that live in a composition and have neither a role rule nor a role-parent rule
(`<security-parents>`) nor an `access-parent`, `internal` or `without-security` setting now follow
the access decision of their container: reading, writing and exporting them is allowed if it is
allowed on the container; creating and deleting them is writing the container. So far such objects
were inaccessible for regular users. Own grants of such a type are no longer evaluated; roles
assigned directly to its objects do not count as role source.

- A type that should decide itself (own grants, directly assigned roles) gets
  `access-parent="self"` on its `<class>` entry of the `SecurityConfigurationService`
  configuration.
- A type used only by application code (transient, or in a context without access checks) is marked
  `internal="true"` (on `<class>` or `<module>`).
- The "Coverage" tab of the access control administration (React UI) and the INFO lines logged at
  start (one per type with an incomplete access definition) show the affected types; the coverage
  view also lists the types marked `without-security`.

```xml
<class name="my.module:Attachment" access-parent="self">
	<grant operation="Read" roles="..."/>
</class>
<module name="my.internal" internal="true"/>
```

Further options: `access-parent="container" access-reference="my.module:Ticket#comments"` (only
via this composition), `access-parent="target" access-reference="my.module:Reminder#ticket"` (target
of a single-valued reference). Optional test for applications: `test-security-coverage="true"` on
`test.com.top_logic.element.util.ElementTestCollector$GlobalConfig` in the `*.test.config.xml`.

Detect: `grep -rn -e 'composite="true"' --include=*.model.xml src/main/webapp/WEB-INF`
and `grep -rn -e 'SecurityConfigurationService' -e 'access-parent' -e 'internal=' --include=*.xml src/main/webapp/WEB-INF`.
Report the composition types without own role source and the decision taken to the user.

---

## 4. React views (`*.view.xml`)

### 4.1 `<object-list input>` renamed to `inputs` (#29597) — mandatory if used
`<object-list input="x">` becomes `<object-list inputs="x">`; the functions `items`, `link` and
`remove` are unchanged.

Detect: `grep -rn -E '<object-list[^>]*\sinput=' --include=*.view.xml .`

### 4.2 `<throw-error>` removed (#29611) — mandatory if used
Replace `<throw-error message="…"/>` by
- `<notify kind="error" stop="true" expr="x -> #('…'@en)"/>` when the chain should merely end with
  the message, or by
- `<execute-script function="x -> throw(#('…'@en))"/>` when the command should fail.

Detect: `grep -rn '<throw-error' --include=*.view.xml .`

### 4.3 `<tree>` attributes removed (#29502) — mandatory if used
The `<tree>` attributes `isLeaf`, `supportsNode`, `modelForNode` and `nodesToUpdate` no longer exist
(they had no effect); a view declaring one of them fails to load. Remove them.

A `parents` expression on `<tree>` that so far had no effect is now evaluated; check that it is
correct (or remove it).

Detect: `grep -rn -E '(isLeaf|supportsNode|modelForNode|nodesToUpdate|parents)=' --include=*.view.xml .`

### 4.4 Forms no longer inset themselves (#29663) — mandatory, review visually
A form grid (`<form>`, `<fields>`, `<config-form>`, `<config-editor>`) no longer pads itself, so forms
in application views lose their automatic distance to the container border. Wherever a `<form>` or
`<fields>` sits directly against a border (panel body, tab, dialog, split pane, detail area), add
`with-inset="true"`:

```xml
<form input="obj" with-inset="true">
  <field attribute="name"/>
</form>
```

`<config-form>` and `<config-editor>` have no such option; wrap them in `<inset>`. Do **not** add the
option where the form already sits inside an `<inset>`, is nested inside an inset form, or where its
sole content is an editable table that should fill the area. (Java: section 1.4.)

Detect: `grep -rn -E '<(form|fields|config-form|config-editor)[ >]' --include=*.view.xml .`
For each hit decide by its parent element.

### 4.5 Theme configuration: dark themes and the system preference (#29528) — mandatory for own dark themes
Users of the React UI who never picked a theme now see the theme answering their operating system's
appearance preference instead of the configured default.

- Every own theme with a dark appearance should declare `color-scheme="dark"` (inherited by themes
  extending it); otherwise scrollbars and form controls keep their light appearance.
- The theme that should answer a dark operating system gets `system-default="true"`; a light theme
  other than the default theme that should answer a light operating system gets it too. A second
  theme marked for the same scheme is a configuration error.
- Where following the system is unwanted, mark no theme as `system-default` (and remove the mark of
  an engine theme if it is overridden): both preferences then resolve to the default theme and the
  "System" menu entry does not appear.
- Application stylesheets with `[data-theme="…"]` rules keep working.

```xml
<theme name="my-dark" extends="default" color-scheme="dark" system-default="true">
	...
</theme>
```

Detect: `grep -rn -e 'UIThemeService' -e '<theme ' --include=*.config.xml src/main/webapp/WEB-INF/conf`

### 4.6 Only registered entry points can be opened by URL (#29551) — mandatory if views are linked directly
A React application that opens views other than its `default-view` directly by URL
(`/view/<window>/<path>.view.xml`, links, bookmarks) must register them as entry points; an
unregistered view is answered with 404 ("No such entry point."). In `<app>.config.xml`:

```xml
<config config:interface="com.top_logic.layout.view.ViewConfig">
	<entry-points>
		<entry-point view="landing.view.xml"/>
	</entry-points>
</config>
```

The default view is an entry point implicitly. Views reached only through `<view-ref>`,
`<open-dialog>` or routes need no registration.

Detect: `grep -rn -E '\.view\.xml' --include=*.java --include=*.html --include=*.jsp --include=*.xml --include=*.properties --include=*.md src | grep -E '/view/'`
— each view file named in a URL (except the `default-view`) needs an `<entry-point>`.

---

## 5. Classic UI and JSPs

### 5.1 Text input templates with buttons (#28474) — mandatory if overridden
The templates `TEXT_INPUT_WITH_BUTTONS_EDIT_TEMPLATE` and `TEXT_INPUT_WITH_BUTTONS_EDIT_MULTI_TEMPLATE`
no longer hard-code the CSS class `lFixedRight` for the button container but use the new template
variable `{inputButtonCssClass}`. Applications overriding one of these templates must take over the
variable; `TextInputControl` still delivers `lFixedRight`, `ExpandableTextInputControl` delivers
`tl-expandable-button`.

Detect: `grep -rn -e 'TEXT_INPUT_WITH_BUTTONS_EDIT' .`

(The CSS class renames of the same ticket are section 6.1.)

### 5.2 Changed labels in scripted tests (#29540) — mandatory for scripted tests
Scripted tests addressing the labels "Abmeldung", "Anmeldung" or "Tel. mobil" must use "Abmelden",
"Anmelden", "Telefon mobil".

Detect: `grep -rn -e 'Abmeldung' -e 'Anmeldung' -e 'Tel. mobil' --include=*.script.xml .`

---

## 6. Stylesheets

### 6.1 Classic controls, command buttons and `PageRenderer`: BEM class names (#28474) — mandatory if referenced
The CSS classes of the controls, the command buttons and the `PageRenderer` were switched to BEM
notation (`block__element--modifier`) with `tl-` prefix. Applications with own stylesheets, own
themes, own JSPs or own control renderers that refer to the old names **silently lose their
styling** and must be adapted.

Command buttons:

| before | now |
|---|---|
| `cmdButton` | `tl-cmd-button` |
| `cmdButtonDisabled` | `tl-cmd-button--disabled` |
| `cmdImg` | `tl-cmd-button__img` |
| `cmdLabel` | `tl-cmd-button__label` |
| `button_minus` | `tl-button-minus` |

`PageRenderer`:

| before | now |
|---|---|
| `fptPage` | `tl-form-page` |
| `fptHeader` | `tl-form-page__header` |
| `fptTitle` | `tl-form-page__title` |
| `fptTitleContent` | `tl-form-page__title-content` |
| `fptTitleText` | `tl-form-page__title-text` |
| `fptSubtitle` | `tl-form-page__subtitle` |
| `fptSubtitleContent` | `tl-form-page__subtitle-content` |
| `fptIconBar` | `tl-form-page__icon-bar` |
| `fptBody` | `tl-form-page__body` |
| `fptBodyContent` | `tl-form-page__body-content` |

Controls:

| before | now |
|---|---|
| `cTextInput` | `tl-text-input` |
| `cExpandableTextInput` | `tl-expandable-text-input` |
| `cBlockTextInput` | `tl-block-text-input` |
| `cIntegerInput` | `tl-integer-input` |
| `cDateInput` | `tl-date-input` |
| `cTimeInput` | `tl-time-input` |
| `cDatetime` | `tl-datetime` |
| `timePart` | `tl-datetime__time-part` |
| `cPopupSelect` | `tl-popup-select` |
| `cDropdownSelect` | `tl-dropdown-select` |
| `cTextSelect` | `tl-text-select` |
| `cTextPopup` | `tl-text-popup` |
| `cTextPopupView` | `tl-text-popup-view` |
| `cBooleanChoice` | `tl-boolean-choice` |
| `cCheckList` | `tl-checklist` |
| `cCheckList-counts` | `tl-checklist__counts` |
| `cDataItem` | `tl-data-item` |
| `cDownload` | `tl-download` |
| `downloadControl` | `tl-download--download-mode` |
| `cIconChooser` | `tl-icon-chooser` |
| `cIconSelect` | `tl-icon-select` |
| `searchTextField` | `tl-icon-chooser__search` |
| `displayedIcons` | `tl-icon-chooser__icon` |
| `cDecoratedCell` | `tl-decorated-cell` |

Not renamed and to be used unchanged are, among others, the layout classes (`lFlexible`,
`lFixedLeft`, `lFixedRight`), `cDecoratedCell2`, `button_plus`, `cTextPopupEditor` and the state
classes such as `selected`, `disabled` and `mandatory`.

New classes:

| class | meaning |
|---|---|
| `tl-expandable-button` | container of the buttons of an `ExpandableTextInputControl` / `BlockTextInputControl`; replaces the former `lFixedRight` there |
| `tl-text-select__option-text` | text of an option in the `SelectTextControl` |
| `tl-text-select__option-clear` | clear button of an option in the `SelectTextControl` |

Match whole class names (e.g. `cTextInput` must not hit `cTextInputFoo`; `cDecoratedCell2` stays).

Detect:
```
grep -rn -w -E 'cmdButton|cmdButtonDisabled|cmdImg|cmdLabel|button_minus|fptPage|fptHeader|fptTitle|fptTitleContent|fptTitleText|fptSubtitle|fptSubtitleContent|fptIconBar|fptBody|fptBodyContent|cTextInput|cExpandableTextInput|cBlockTextInput|cIntegerInput|cDateInput|cTimeInput|cDatetime|timePart|cPopupSelect|cDropdownSelect|cTextSelect|cTextPopup|cTextPopupView|cBooleanChoice|cCheckList|cCheckList-counts|cDataItem|cDownload|downloadControl|cIconChooser|cIconSelect|searchTextField|displayedIcons|cDecoratedCell' \
  --include=*.css --include=*.jsp --include=*.jspf --include=*.java --include=*.xml --include=*.js --include=*.html src
```

### 6.2 React design system: buttons, app bar, custom properties (#29617, #29540) — mandatory if referenced
- The CSS classes `tlReactButton`, `tlReactButton__image`, `tlReactButton__label` and
  `tlReactButton--primary|--link|--small|--large|--icon|--iconOnly|--labelOnly|--active` no longer
  exist (#29617). A theme styling `tlReactButtonActive` targets `.tl-button[aria-pressed="true"]`
  (#29540). Rewrite rules against `tl-button` and its modifiers, or
  better drop them: the appearance is chosen by the server state (`appearance`, `tone`, `size`) or
  the container context. A pressed button is `[aria-pressed="true"]`, a busy one
  `[aria-busy="true"]`; there is no `--active` class.
- The app bar with `.tlAppBar--primary` is no longer painted in the accent color but uses the design
  system's layer surface. An application relying on the accent-colored header needs an own rule.
- Custom properties starting with `--tl` are reserved for the design system. The application must
  not define new ones (reading the tokens is fine).
- Themes defining `layer-02`, `border-strong` or `shadow-menu` differently from the standard themes
  will see their popups follow those values (#29525).

Detect:
```
grep -rn -e 'tlReactButton' -e 'tlAppBar--primary' --include=*.css --include=*.xml --include=*.ts --include=*.tsx --include=*.java src
grep -rn -E '^\s*--tl[A-Za-z-]*\s*:' --include=*.css src
```

---

## 7. Further notes (no action required)

- **Menus and app bar (#29525):** `display` and `css-classes` of a view command now take effect
  wherever the command is rendered (app-bar buttons may change their presentation; CSS workarounds
  that select a command's button by its icon can be replaced by `css-classes`). Drop-down options,
  chips and read-only displays show the icon of the option's type (register `ThemeImage.none()` for
  a type that should not show one). The session language is no longer fixed at login; a language
  change rebuilds the control tree of the browser tab and discards transient view state. Logging in or
  out no longer keeps the page the session was on.
- **Locale-dependent state (#29525):** an application caching locale-dependent state per session
  should invalidate it when `SubSessionContext#getCurrentLocale()` changes; resolving a `ResKey`
  while constructing a shared object (a `UIElement`, a cached model) belongs where the object is
  rendered for a session.
- **User menu (#29540):** `<language-commands>` / `<theme-commands>` groups are headed "Language" /
  "Theme" (change with `<label>`, an empty key for none); the account area of `user-menu.view.xml`
  shows only the Login button for an anonymous session; the theme and language in force are enabled
  and bold.
- **TL-Script localization (#29555):** `label()`, `localize()` and `fill()` in compiled expressions
  now localize per reading user instead of the locale of the compiling thread.
- **`modifiedRevision()` (#29681):** considers reference and translation changes; attribute storages
  no longer "touch" the owner object. Code relying on a translation change moving the modification
  date of the object row uses `modifiedRevision()` instead.
- **Date display (#29438):** a `tl.core:DateTime` attribute without own format annotation is displayed
  in the React UI with medium date and short time (no seconds).
- **SSO without account (#29624):** a configurable notice page `unknownAccountPage` of
  `ApplicationPages` replaces the login form when an externally authenticated user has no account.
- **Further new features:** uniqueness constraints on the model (#29006), virus scan of uploads via
  `upload_virus_scan_*` variables (#29004), history compaction and purge of deleted objects
  (#27490, #29603), configurable upload size limit (#29560), versioned URLs of `ClientResources`
  files (#29648), TL-Script `trim`, `trimStart`, `trimEnd` (#29670) and `objectId` /
  `objectResolve(id, typeOrTable)` / `objectTable` (#29530, #29639; `objectResolve` gives nothing for
  an object the user may not read).
- **Features introduced and changed within this release cycle:** the migration sections of #29542
  (`<text-input>` → `<value-input>`; `<text-input>` was not contained in any release) and #29617 (`<color role>` instead of `value` / `token`,
  `ValueColor` API, `tlPill` / `colorRole`, React token `support-info`) describe changes to elements
  that did not exist in 8.0.0-alpha8 (they came with #29530 and #29546 in this cycle). An application
  upgrading from the released 8.0.0-alpha8 has nothing to migrate there; only a project that used a
  snapshot build in between must follow those sections. The migration `Ticket_29617_color_role`
  finds nothing to change in an 8.0.0-alpha8 database. The "wave 2" part of #29617 (`ModeSelector`
  `editMode`, `disabled` field state) ships with 8.0.0-alpha10, not with this release.
- **URL attributes (#29548):** a `tl.util:URL` field without scheme gets `https://` prepended; the
  server rejects a non-empty value that is no absolute URI ("Invalid web address").
- **React forms and access rights (#29675):** saving checks the write right of every change; select
  options only offer objects the user may read.
- **Developer commands (#29680):** "Ressourcen neu laden" and the other developer and debug commands
  of the classic UI are executable for root only; the scripting toolbar is hidden for the anonymous
  session.
- **Upload size of the React UI (#29560):** configurable via `max-upload-size` of
  `com.top_logic.layout.react.control.upload.UploadConfig` (default 50 MB) instead of a fixed
  `multipart-config` in the engine's `web-fragment.xml`.
- **Fixes without action:** `CollectionUtil.removeDuplicates()` keeps the order (#29698);
  `security.xml` grants for a scope introduced on the same start are no longer lost (#29562).

---

## 8. Verification checklist

1. `mvn clean install` of the application with Maven 3.8.9 or newer (with tests if possible).
2. Start the application against a copy of the production database. Read the startup and migration
   log: no configuration errors (`use-default-security-parent`, removed `<tree>` attributes,
   `<object-list input>`, `<throw-error>`, `system-default` twice for one scheme); the migrations
   `Ticket_29512_…`, `Ticket_29540_…`, `Ticket_29548_…`, `Ticket_29563_…` and `Ticket_29590_…` ran.
3. Log in as administrator and as a regular user; open every view (classic and React) and every
   dialog. Check that views protected by `SecurityObjectByExpression` are reachable for the intended
   roles (step 3.1), that the additive grants do not open types too widely (step 2.2) and that
   composition parts are accessible exactly as intended (step 3.2; "Coverage" tab). Open every view
   URL the application links to directly (no 404, step 4.6).
4. Check the styling of buttons, inputs and form pages (sections 6.1, 6.2) and the distance of
   React forms to their container border (step 4.4).
5. Switch the operating system to dark mode and check the theme of a user who never picked one
   (step 4.5).
6. Run the scripted tests.
7. Report to the user every step that was skipped, needed a decision, or touches data (default group,
   access changes of steps 3.1 and 3.2, required Maven version).
