[Ekhorn]

Description

A child theme with parent=openremote can override a page's .ftl and ship its own resources, but its CSS never loads: styles= in theme.properties becomes a <link> only in a FreeMarker theme, and these pages are a compiled bundle. The one thing a custom project is most likely to want, is their own stylesheet. These changes allow a custom stylesheet to be applied on top of ours.

Changelog

• An inline script in the generated template reads orStyles from the theme properties Keycloak already sends and writes a <link> per entry into the head, after the bundle's own so the child wins. Paths resolve against the theme's resources, as Keycloak's styles= do, and an absolute URL is passed through.
• In the head rather than appended from the bundle, so the browser holds the first paint for them exactly as it does for Keycloak's own styles=. Appended, they arrived after the page had been built and painted in this theme's styling, and it visibly flipped; in WebKit the components were built before the child's rules existed at all. index.html therefore places the bundle's own tags itself, with inject: false.
• orStyles rather than Keycloak's own styles, which is inherited from the fallback theme and is what the pages this theme does not implement are rendered with: reading it would put the fallback theme's stylesheet on these pages, and declaring our own would take it away from theirs.
• The dev server applies a child theme's orStyles when OR_CHILD_THEME points at its login directory, and keeps the page hidden until they have loaded, as a real page does. yarn start:example runs it with a small example theme in theme/ui/dev-server/example-theme.

Effect on custom projects

A theme mounted under /deployment/keycloak/themes with parent=openremote and orStyles=css/custom.css now has that file loaded on every page this theme implements. With --spi-theme-cache-themes=false --spi-theme-static-max-age=-1 on the container, editing it is a browser refresh.

It can also be worked on without a container: OR_CHILD_THEME=/path/to/custom/project/deployment/keycloak/themes/acme/login yarn start in theme/ui serves it to the dev server, which reloads the page when the stylesheet changes.

That stylesheet is on the critical path, as Keycloak's styles= has always been: a slow one is a slow login page. Two things it cannot hold back, both in the README: a web font with font-display: swap, which is what Google Fonts' URLs ask for, and an entrance animation or transition that runs while the page is hidden for the realm's branding, which wants scoping under html:not(.or-booting).

A realm that sets styles in manager_config.json still wins the brand colour: those are injected after everything else, and the demo configuration carries --or-app-color4 by default. A child theme changes the rest, and the brand colour belongs to the realm.

[wborn]

This is an initial AI-assisted review.

The addition of orStyles provides a straightforward mechanism for custom projects to extend the compiled OpenRemote Keycloak theme without rebuilding it.

The implementation is small and follows the intended behavior:

• Stylesheets are read from the theme's properties.
• Relative paths resolve against Keycloak's theme resources directory.
• Absolute HTTP(S) URLs are preserved.
• Stylesheets are appended after the bundle's own styles.
• Existing Keycloak styles properties remain separate, preserving fallback theme behavior.

The README documents the configuration and explains why orStyles is needed instead of the standard styles property.

No additional code issues were identified in the three changed files.

A real child-theme deployment should still be tested to confirm that Keycloak supplies the expected resources URL and inherited properties, and that the custom stylesheet is actually loaded on an implemented page.

AI found no further issues in the reviewed change. Manual maintainer review is still needed before merge. This PR also remains marked as a draft.

[richturner]

This seems like a useful change, would it be much effort to include a mock example theme just for dev testing purposes?