[Consulting] CSS version prefixes

[ej612]

Hi there,

The components' CSS classes carry a version prefix to ensure peaceful coexistence of multiple different versions in the same frontend.

For example, the internal CSS class

--_ui5_side_navigation_width

is compiled to

--_ui5-v1-24-26_side_navigation_width

In SAC, we reference quite a couple of these classes. This means that whenever we update the UI5WC packages, we need to revisit all of them and update the prefix.
I have tried to automate this by constructing the prefix like so:

import versionInfo from '@ui5/webcomponents-base/dist/generated/VersionInfo';
const cssClass = `var(--ui5-v${versionInfo.major}-${versionInfo.minor}-${versionInfo.patch}_side_navigation_width`;

However, VersionInfo is exported by the base package. Does this mean that the resulting version will be that of the base package, which might or might not correspond to the version of the main and fiori packages that define the CSS classes? And if this approach doesn't work, is there a recommended way that would spare us the pain of having to do this manually on each upgrade?

This issue has appeared on our radar because we are currently in the process of updating from 1.24.24 to 1.24.26 and there is some confusion around which version prefix to use:
Intuitively, we have added _26, which doesn't work. By looking into the compiled code, we can see that the prefix for .26 is _25:

1. Open package
2. Go to dist/css/themes/SideNavigation.css
3. [CTRL] + [F] -> _side_navigation_width

Edit:
A solution to this problem could be for you to export your CSS classes as an enum, which means we wouldn't have to deal with the prefixes at all anymore.
Similarly to how the react package handles this with ThemingParameters.
I understand this would require some refactorings, including setting up CSS modules if you don't currently use them, so I don't know how feasible this would be.

Can you shed some light on this?
Thanks!

[nnaydenow]

Hi @ej612,

These variables are considered private and are not intended to be used or modified outside the component’s scope. They are subject to change—such as being removed or renamed—because they depend on the internal DOM implementation of the components. There is no way to avoid this in order to keep these variables stable.

If you want to modify the visual appearance of the components, this should be done using --sap* theming parameters, styles applied to the custom element itself, or via parts for internal customization. There are, however, some limitations:
--sap* variables are stable and safe to customize, but using parts may require adjustments when upgrading versions, as overrides depend on the internal DOM and CSS implementation. The contract is only to expose the parts themselves; customization and its maintenance are the responsibility of the application. In most cases, overriding colors and sizing styles is safe.

Regarding your question: yes, the version prefix currently points to the base package version. UI5 Web Components packages depend on the base package, which means that version 2.18.0 of the main package uses version 2.18.0 of the base package. If a different base package version is loaded by the application, it will run in a different runtime than the components.

Does this answer your question, or would you like us to clarify any part in more detail?

Regards,
Nayden

[ej612]

Hi Nayden,

Thank you for your reply.
To give you some more context, SAC is an application where multiple different UI libraries coexist, and unfortunately, it is sometimes necessary to reference these internal variables to style a custom element in such a way that it blends in with the UI5WC elements. I believe we only ever read these, never modify them.

I understand that you consider these to be private and it is, of course, legitimate for you to say "What you're doing is unsupported" and to stop there. But knowing that there are use cases where people have to reference these, it might still make sense to think about my proposition of exporting these as enums on a per-component basis. That way, we would get type errors if an upgrade renames or removes a class, on top of sparing us the pain of having to deal with the prefixes.

[ilhan007]

Hello @ej612
others from SAC use getScopedVarName, f.e:

import { getScopedVarName } from @ui5/webcomponents-base/dist/CustomElementsScopeUtils.js

getScopedVarName("--_ui5_button_base_height"); // --_ui5-v1-24-26_button_base_height

The method will return the version scoping prefix.
However, this is only a workaround, ui5_* vars are not public - could be removed, renamed, etc.

[ej612]

Hi Ilhan,
Thanks for this helper, I didn't know about it. Seeing how it's based on VersionInfo, I imagine it has the same problem of appending the wrong syntax if the base package version is different from those of main & fiori?