proposal: explicit custom-pseudo-element definition about stylable HOT 4 CLOSED

We should also document nested parts and pseudo elements overriding possibilities when combining nested parts and -st-extends

from stylable.

I wrote in the proposal about nested parts:

In the future we might want to allow nested parts definitions to provide a way to describe deep structure API

I think the first iteration of this will not include parts definitions with body that will allow extending, adding states or defining inline styles, but I can definitely see this extending in this direction.

It isn't detailed, but I assume it will follow the same rules as a root extending another definition, just inline. So for example we could have an Accordion component with a header that extends something and defines nested parts that would override definitions from the extended definition:

/* accordion.st.css */
@st-part ::header {
    -st-extends: Box;
    @st-part ::icon {}
    @st-part ::title {}
}

From the outside: in case the Box had an icon, it would be overridden by the Accordion icon, while the Box frame that is not overridden can still be accessed.

@st-import Accordion from './accordion.st.css';

/* style the accordion icon inside the accordion header */
Accordion::header::icon {}

/* style the Box frame of the accordion header */
Accordion::header::frame {}

from stylable.

Looking a bit forwards at issues with the nesting mechanism, we encountered some aspects that needs more clarifications.

Implicit class

When implicitly mapping a part to a class the part inherits the class definition:

@st-part ::navBtn;
.navBtn {
    -st-extends: Button;
}

/* .local__navBtn .button__label */
::navBtn::label {}

/* .local__navBtn .button__label */
.navBtn::label {}

Inherit Sugar

Adding -st-extends under the part is syntactic sugar for setting the class to extend the extending reference.
For example the following code is sugar for ::navBtn pseudo-element mapping to .navBtn class and setting the .navBtn class to extend the Button component.

@st-part ::navBtn {
    -st-extends: Button;
}

/* .local__navBtn .button__label */
::navBtn::label {}

/* .local__navBtn .button__label */
.navBtn::label {}

Nesting Parts

Adding a nested part defines style API to the part under the specific pseudo-element, and overrides the access to a part with identical name if it exist in the inherited extend, but doesn't change the class definition(!):

@st-part ::navBtn {
    -st-extends: Button;
    @st-part ::label;
}

/* .local__navBtn .local__label */
::navBtn::label {}

/* .local__navBtn .button__label */
.navBtn::label {}

The code above overrides the ::label pseudo-element just under the ::navBtn without effecting the .navBtn class.

Notice that we focus on definition of parts, but definition of states would work in the same way.

Multiple Identical Parts and collisions

There are cases where we want to have a part with the same name/class available in multiple placed in the structure:

/* top level nav button that targets all navigation buttons */
@st-part ::navBtn;
@st-part ::header {
    /* match more specific navigation buttons under the header */
    @st-part ::navBtn;
}

/* .local__navBtn */
::navBtn {}

/* .local__header .local__navBtn */
::header::navBtn {}

In this case setting -st-extends in one of the ::navBtn definitions would prevent setting -st-extends in another, or directly inside the class definition, just as -st-extends cannot be set in the same class more then once:

@st-part ::navBtn {
    /* this extend will be used */
    -st-extends: Button;
};
@st-part ::header {
    /* match more specific navigation buttons under the header */
    @st-part ::navBtn {
        /* ERROR: already extended */
        -st-extends: Other;
    }
}
.navBtn {
    /* ERROR: already extended */
    -st-extends: Other;
}

from stylable.

closing in favor of #2848

from stylable.