User Story

As a developer, I want to use CSS variables in my custom ZK themes, or in my additional stylesheets supplementing themes in my ZK application.

CSS variables usage have two main steps.

Step one: variable declaration

CSS variables are similar to default CSS rules. A CSS variable is declared through a CSS selector, which can target none, one or multiple elements.

A CSS variable is inherited by descendants of the original elements.

A CSS variable can be overridden by another declaration of the same through a higher priority selector (ex: .class1{} has a lower priority than .class2>.class1{})

A Css variable's name starts is "--"

Step two: variable used in a different CSS rule

If a CSS variable is resolved at element level, rules applied to this element may use the css variable such as:

selector{
    cssproperty: var(--variable-name);
}

for example:

:root{
    --var1: "100px";
}

.target{
    height: var(--var1); //resolves as height: 100px;
}

See here for an illustration of the virtual ancestor issue

https://zkfiddle.org/sample/s79jtm/2-ZK-css-variable-support

ZK should not care about CSS variable usage, just make sure that a declared variable is available to all logical descendants of the selected object.

A developer may declare variables directly in CSS (an bypass ZK integration), or use ZK integration.

The only cases where simply passing the declared variables to the client such as

:root{
    #uuid1{
       --var1: "abc";
    }
    #uuid2{
       --var2: "def";
    }
    etc.
}

is with virtual descendants.

To evaluate and decide on spec: Should ZK provide automatic CSS variable inheritance for virtual descendants, such as popups or other components that are not directly attached to the parent component's DOM node in the resulting page.

(see link above)

If so, we would need to redeclare the resulting rule set for the virtual children. in the case of popups that may be opened on multiple anchor, we should use the declared relationships, rather than the target open() anchor.

For example:

		<div sclass="example4">
			<button popup="myPopup"></button>
			<popup id="myPopup">
				<div sclass="target"></div>
			</popup>
		</div>

 In this situation, the popup "myPopup" is a descendant of example4, so it should receive the rules applied to example4, even if it is opened on a different anchor

Acceptance Criteria

Provide a  broad support (at HtmlBasedComponent or similar) to do operations such as:

component.setCssVariable(variableName, variableValue)

(when generating the resulting CSS code, if a component hold a variable with the same name as the ancestor, the component should redeclare that variable with the new value. If an ancestor has a declared variable, which does not have an overriding declaration, the variable should be inherited from the ancestor)

Note: in most cases, regular CSS inheritance will already provide this functionality, but not for virtual descendants (see above)

component.getAncestorWithCssVariable(name)

will return the first component holding a declared css variable for the matching variable name in order from the current component to the root component. may return the same component if this component is holding a variable of this name

component.setCssVariable(name)

will override if there is already a variable declared with this name on the same component

component.getCssVariable(name)

component.removeCssVariable(name)

(can be combined such as

component.getAncestorWithCssVariable(name).removeCssVariable(name)

Details

https://www.w3.org/TR/css-variables-1/

https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

https://css-tricks.com/a-complete-guide-to-custom-properties/