wix / stylable

Stylable - CSS for components
https://stylable.io
MIT License
1.26k stars 62 forks source link

feat(core)!: normalize build-var value #2921

Closed idoros closed 8 months ago

idoros commented 8 months ago

This PR modifies the evaluation method for the Stylable build-vars value to ensure its consistency with other values.

Please note, this introduces a breaking change. We had initially deferred this adjustment until version 6. However, to streamline edge cases, we've decided to alter the behavior now.

Previous Behavior

In the past, the build-var value wasn't assessed in the same manner as other values. This discrepancy led to symbols defined within it being overlooked, especially when referencing a custom property.

For instance, using buildVar: var(--dynamicVar) wouldn't define the --dynamicVar symbol. As a result, the evaluation of the build-var would retain a global, un-namespaced custom property. Complicating matters, if this property was defined outside the build-var, it would be namespaced. This behavior can be preserved (shown below).

Another case that is being deprecated/fixed is when evaluating a build-var, it would pickup custom-properties from the evaluated context. That was an unintentional/undocumented/weird behavior that we don't think should be supported, have seen no cases of anyone using it, and unlike the global/undeclared behavior that can be preserved, this "fix" doesn't have any alternatives.

Retaining the Old Behavior

For legacy code that sets a build-var with a global custom property and wishes to maintain the previous behavior, there are two solutions:

Enclose the value in quotes:

:vars {
    buildVar: "var(--dynamicVar)";
}

Define a global custom property:

@property st-global(--dynamicVar);
:vars {
    buildVar: var(--dynamicVar);
}

Notice that a deprecation info diagnostic is introduced in stylable@5 to report unknown custom-properties in build-vars: https://github.com/wix/stylable/pull/2922