sinuous-style
Scoped styles for Sinuous à la styled-jsx.
Installation
There are two ways to consume sinuous-style
ESM
Run the following inside your project directory:
npm install sinuous-style
At present, there is no configuration. You can use it wherever you are using Sinuous. It's possible this may change to make it more flexible.
CDN
Put this into your HTML:
Be sure you place it below your Sinuous CDN, like this:
This places a sinuousStyle
property on the window
object.
Usage
Start by importing the sinuous-style api.
For ESM:
;
For CDN:
let html svg = windowsinuousStyle;
Then simply use the sinuous-style html
and svg
throughout your project in place of the Sinuous html
and svg
.
html
and svg
The syntax for html
and svg
is similar to the Sinuous html
and svg
. The difference is that they they can be passed a string that will be used to scope the elements and styles within the markup.
With regards to scoping, there are three things that you might want a call to html
or svg
to do.
- Set a new scope
- Propagate the outer scope
- Block outer scopes
For all examples, I will use html
, but the examples apply similarly to svg
.
Set a New Scope
The user must pass a string to the call to html
that will be injected as a class name on all elements within that scope.
let view = ` <p>Some text.</p>`;
Results in:
Some text.
Propagate the Outer Scope
This is particularly useful in the case of conditionals and other nested calls to html
that logically ought to belong to the same scope as the rest of the elements in the component.
let view = ` <p>Some text.</p> `;
Results in:
Some text.Some more text.
Block Outer Scopes
let view = html` Some text.`;
Results in:
Some text.
And:
let view = ` <p>Some text.</p> `;
Results in:
Some text.Some more text.
Warning:
Sinuous' html
and svg
will propagate scopes, not block them. So be careful if mixing the api from Sinuous and the api from sinuous-style. It is recommended that you not do that.
<style>
Regular style tags with no local
or global
directives (<style>
) act the same way they always do in Sinuous.
<style global>
Passed the global
directive, only one style element will be added to the dom regardless of how many times the component is rendered. It will also be appended directly to the <body>
instead of being added where the component is rendered to the dom.
As in styled-jsx, dynamic styling rules can be placed in separate style elements for performance reasons. To support multiple global
style elements, give each a class unique to that scope.
For example:
<!-- Dynamic Style --> <!-- Static Style -->
<style local>
Passed the local
directive, the style element acts exactly like <style global>
except that all selectors will be scoped to the scope name.
For example:
let view = ` <p class="some-other-class">Some text.</p> <style local> p { padding: 5px } </style>`;
The component renders to the dom as:
Some text.
And the style element renders to the dom as:
Separating dynamic local
styles from static local
styles works in the same fashion as it does for global
styles.
Limitations
Usage of >
, ~
, and +
in selectors must be surrounded by whitespace.
Do div > p
, not div>p
.
Scoping within any @-rules, such as media queries, is not supported.
Scoping individual selectors with :global()
as in styled-jsx is not currently supported.
Differences from Styled-JSX
Unlike styled-jsx, sinuous-style is a runtime library. So it lacks some of the affordances of a compiler/transpiler library.
Namely, in sinuous-style, the unique string for establishing the scope must be entered by the user, whereas in styled-jsx the scope string is generated by the library. So there are a few syntax differences as a result.
Another difference, as mentioned above, there is presently no support for :global()
to selectively block scoping on a particular selector.
Contributions
Pull requests and feedback are welcome! Please raise any issues or bugs that you find.
Acknowledgments and Thanks
- Author of Sinuous
The whole team behind styled-jsx
- The inspiration behind this library