Need a way to define custom mapping in order to support none stylable libs:

CSS API:

/* example-custom.css */
.root{
    -sb-states: toggled(".on"), loading("[data-spinner]");
}
.root:toggled { color:red; }
.root:loading { color:green; }

CSS OUTPUT:

/* namespaced to example-custom */
.root.on { color:red; }
.root[data-spinner] { color:green; }

Currently docs CSS output is declaring that the selectors shown are "scoped" or event "scoped to *". I'm not sure it's clear and it get confusing in some examples that involves multiple stylesheets.

I think we should switch back to putting @namespace "X" in every example and show the actual CSS output.

Problem:

• :hover handling on mobile is bad (hover is activated on touch, but doesn't get deactivated until you touch something else), so we need to disable hover on mobile
• :active on mobile provides the same functionality as :hover on desktop. So it is preferred that we remap :hover to :active on mobile, unless :active is explicitly specified by the user.

Proposed solution:

• When encountering :hover in CSS, auto-create a media query, something along the lines:

@media (hover: none) {
    .root:hover {
           /* reset the rules */
    }
    .root:active {
        /* put original hover rules here */
    }
}

• Do the above unless there is also a :active selector present for the same selector. In that case, just reset/remove the hover.

At the moment any namespace is composed of @namespace + file content hash.

• add hash only in cases of conflict and we can use a simple counter instead of hash
• use filename as default @namespace

In case of CSS standalone export we can generate better or configurable namespace, but its not in our short term goals.

• Link to available known project (when we'll have)
• Install / import - same steps create components (source components)

currently master runs less tests on terminal than webpack-dev-server

In node

In webpack

need to explain how vars of a theme are overridden as a special case of vars reference.

Custom selectors

// ToDo: write docs
// https://tabatkins.github.io/specs/css-aliases/#custom-selectors
// polyfill custom selector + expose as pseudo element

Use cases

Container / recursive components

// tree node example

Expose deep inner parts

Interface for non-Stylable

• variable source comment next to resolved values

  include a comment in target CSS (available in browser CSS dev tools) that will indicate the source of values that are derived from variables. (should include a file path, as well as a variable name)

• variable override (in var source location)

  enable overriding variables (in their source location), in order to allow real-time debugging of their effects

• file separators between CSS rulesets

  in developer tools expose file separators at relevant component bounds

Received the following error due to a missing underscore in a "value" function. E.g the import was named color_Main_Text but was used as value(color_MainText).

• need to add references and guides on how to use layouts and how to build layouts in Stylable

we'd like to use something that doesn't have a native HTML counterpart

• stylable-basics for example.

Per @idoros we can use Gallery built this way:

.root {
    -st-states: empty, inTransition;
}
.navBtn {
    -st-states: previous, next;
}
.mainImage {
    -st-states: shown;
}
.thumb {
    -st-states: previous, current, next;
} 

Exporting of multiple variables from theme is not that easy
Right now exporting of multiple variables looks like this

:import(@theme) {                                                                                                                                                                                                                             
  -sb-named: inputBorder, borderRadiusInput, fontSizeSmall, lineHeightNormal, fontFamily, textMain, backgroundHover                                                                                                                           
} 

Using * or any other character for bulk export (like in es import statement)

:import(@theme) {                                                                                                                                                                                                                             
  -sb-theme: myTheme                                                                                                                          
} 

Hi!
I reciently updated the stylabale from 0.0.12 to 1.0.2 and static property stylesheet from component moved to it render function

I think it related to different wrapping approach.
In new version you wraps the render which replaced with new react component and this new component has the stylesheet as static property, but as subsequence this property accessible from via render

Just to clarify:
0.0.12

@SBComponent(styles)
class A extends React.Component<{}, {}> {}

A.stylesheet.get('class-name')

1.0.2

@SBComponent(styles)
class A extends React.Component<{}, {}> {}

A.prototype.render.stylesheet.get('class-name')

Add support for CSS Modules Composition behavior.

When I define a class .classA and then in .classB { -st-composes: classA }, then I would inherit all of its styles.

Without importing a variant.

CustomTag:customState(val) {}

Transform to:

.root CustomTag_root[data-CustomTag-customState="val"]

Usage example:

.myForm::field:name(title):empty{
    background:blue;
}

Sections:

about:

this is what is imported instead of css...

• small size

api:

-root
-get
-csStates

manual integration:

if not using stylable-react-component you should...

manual creation

for projects without stylable-integration
for tests

see pseudo-elements docs.

Currently, looking at mixins reference page one cannot find how are they defined and parametrized (mixins with parethesis). Variants page gets this right, both usage and definition are described well. Would be nice to have the same structure for mixins page, too.

Install, Configure and Build

Install it for a project

npm install stylable

best practices for WebPack or other popular build tool with React
(Then other options - clean project w/ no build and/or no React)

Stylesheet file
Component file

Import stylesheet into component file

What part of library has been loaded into runtime. Don't want to bring parser and other stuff into client-side. Different between working at build time or runtime. We recommend build time but then need WebPack or other build tool. Must be decided while users working cuz depends on what has to be imported. (Maybe some debugging options can give.)

Don't have to provide source maps for CSS. Cuz everything is compiled down to CSS. Debug mode could give you comments on where the rules came from.

Add to feature list: Debug comments added to CSS - where did styling come from to produce CSS. Configure how you want CSS outputted. Removed for production -

Good to have "create app" instruction

npm stylable - what will user get?

• boilerplate

Specificity document - transpiler switch to show specificity or comment to show specificity

List of 50 components
CSS mixin of how something looks - UI kit to provide mixins and enable writing your own
some containers need component

Provide instructions for writing own mixins or CSS or JS

TUTORIAL

2 component files

Document css.ts file - used for only internal use. not documenting JavaScript API

generateSVGURL - mixin

vbox, hbox, grid - will be mixins
But more complex layouts have to be components
Component is needed only if logic needed to build it.

StylableReact - POC

Create component file as .tsx - social-button.tsx
Create a css file - social-button.css (social-button.css.ts)

For each component have a different CSS file. Associate component with CSS file in the component ts file.

Styling social button from the outside:
Add a className in tsx file.

In CSS for

• rules are added at the position that the -st-mixin is declared
• appended selectors are added directly after the rule-set that the mixin was applied to
• multiple mixins are applied according to the order that they are specified in

CSS API:

.a{
    color:red;
    -st-mixin: golden;
    background:white;
}
.a:hover{
    background:white;
}

CSS OUTPUT:

.a{
    color:red;
    color:gold; /* added by golden */
    background:black; /* added by golden */
    background:white;
}
.a:hover{
    color:gold; /* added by golden */
    background:black; /* added by golden */
}
.a:hover{
    background:white;
}

running on mac with

"stylable": "4.0.10",
"stylable-integration": "5.1.0",

changes in theme don't take place unless I kill node and run it again.
@barak007 If you need my exact setup let me know 💃🏼

React.cloneElement(<div>, {cssStates: {...}});

The cssStates prop simply gets added onto the div, and React warns about unknown property.

Definitely stylable

Use custom selectors, global selector and custom pseudo-classes mapping to describe style interfaces for components that were not originally build with Stylable.

Example

For a BEM toggle button with icon component:

<button class="btn"> /* potentially contain `.btn--toggled` class */
    <span class="btn__icon">
    <span class="btn__label">
<button>

Interface stylesheet

A separate "interface" stylesheet can help describe a way to style it:

/* external-toggle-button.css */
.root {/* ToDo: way to override root selector */
    -st-states: toggled(".btn--toggled");
}
:--icon :global(.btn__icon);
:--label :global(.btn__label);

Usage

Use like any other Stylable stylesheet to style:

CSS api:

:import {
    -st-from: "./external-toggle-button.css";
    -st-default: ToggleBtn;
}
.my-btn{ 
    -st-extends: ToggleBtn;
    background: red;
}
.my-btn:toggled {
    background: green;
}
.my-btn::label {
    font-size: 20px;
}

CSS output:

.my-btn { 
    background: red;
}
.my-btn.btn--toggled {
    background: green;
}
.my-btn .btn__label {
    font-size: 20px;
}

// add more cases... missing real-world CSS usage

:import {
    -st-from: "./path";
    -st-named: param1 as P1;
}

will not resolve param1

Currently docs reference for variant contains two topics.

• Variant as as syntax: not automatically outputted to CSS
• Mix CSS classes using -st-extends and -st-mixin

This page isn't clear to me.

How does external-toggle-button.css get wired up to the BEM component?
(I assume an import, but docs shouldn't leave me guessing).

It appears that a custom property :--icon and :--label are set up as
"aliases" for things inside the BEM component, but then are never
used, so I don't really get to understand the full use.

(unless .my-btn::label is styling the BEM label rather than an HTML
element, in which case PLEASE let's not confuse people by hijacking
HTML elements as class names).

And if external-toggle-button.css needs to :import the BEM component from
www.thirdparty.com/BEM.html, why don't we just do -sb-named: btn__icon
as icon, btn__label as my-label rather than set up custom properties?

It looks to odd when you have to create a instance (which is not used anywhere) to declare the vars

new Stylesheet({                                                                                                                                                                                                                            
    ':vars': theme,                                                                                                                                                                                                                           
    '@namespace': '@theme'                                                                                                                                                                                                                    
})
Stylesheet.context.attach() 

I suggest to create static method in context instead

Stylesheet.context.addVars('@theme', theme) 

VsCode and doc managers in general use file:// protocol to provide paths, Stylable resolver crashes on this.
Hacking this from the outside is hard (no success yet), since you need to pass it a MinimalFS that has readFileSync which gets used in different contexts. So I can't pass it an FS that adds (or removes) file:// prefix.

compose example isn't clear in the sense what you are getting out of it. The css output isn't really helping here. We should see the service this operation provides.

cc: @barak007, @AnnieLR

in explanation of 'namespace'

At the moment selectors with same value are merged:

.a { color:green; }
.b { color:red; }
.a { background:purple; }

will invalidly transform to:

.a { color:green; background:purple; }
.b { color:red; }

Import currently allow default and named imports.
allow something like:

@st-import * as Everything from "./a";

Equal to in JS:

import * as Everything from "./a";

Where Everything is the reference to the entire module's contents.

Need to understand how access the exports in CSS:

.some-cls{
    -st-extends:Everything.something; /* doesn't look good in CSS */
}

sb seems like the wrong prefix: st, core, style, wix etc looks better.
stylesheet.context.attach is a bad name. Should be named something like renderCSS. In other words, something which implies that this is the function which renders the CSS to the DOM.

use ifndef to namespace of styleable.

I have a class and a selector:

.blue {
    -st-mixin: MyMixin(1, 2, 3);
}
.blue.small {
    -st-mixin: MyMixin(4, 5, 6);
}

that I want to bring into the class using nested classes:

.blue {
    -st-mixin: MyMixin(1, 2, 3);
    &.small {
        -st-mixin: MyMixin(4, 5, 6);
    }
}

The generated CSS does not activate the mixin with (4, 5, 6) when the small class is also applied (It applies the original, (1, 2, 3) mixin)

Make sure that either -st-extend or -st-compose work on Component selectors in order to mix in other classes

It would be nice to use special character for variable instead of value(varName)
Something like sass doing ($varName) or less (@varName)

This is the error message when importing like:

:import{
    -sb-from: 'blah blah blah'
}

instead of

:import{
    -st-from: 'blah blah blah'
}

// ToDo: write docs - future

CSS declaration value manipulation

.a{
    color: darker(#FFFFFF);
}

:import {
-st-from './somewhere.st.css';
-st-default: List;

.item {
-st-states: focused;
}

Now, this:
List.item

Should throw error, because List and .item are differently-typed

source:

.a { 1 }
.a:hover { 2 }
.a, .b, .a .c { 3 }

.x {
    -st-mixin: a;
}

target:

.a { 1 }
.a:hover { 2 }
.a, .b, .a .c { 3 }

.x { 1 } 
.x:hover { 2 } 
.x, .x .c { 3 } /* .b is removed since its not part of the mixin '.a' */

.x, .x .c { 3 } - not outputted today - bug

All code examples in this document need to be rewritten along with whoever actually develops the component.

@abumami Please work on this ASAP, so we also have a proper example in the documentation

@maksymc FYI. who is the dev working on this? where did you get the current example code?

Send error diagnostic when importing in -st-named: a name that isn't exported from the -st-from: