Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
styleQ is a quick, small JavaScript runtime for merging the HTML class names produced by Atomic CSS compilers.
Install:
npm install styleq
Import:
import { styleq } from 'styleq';
Merges style objects and produces a DOM className
string and inline style
object (camelCase property names).
const [ className, inlineStyle ] = styleq(styles.root, { opacity });
The styleq
function efficiently merges deeply nested arrays of both extracted and inline style objects.
$$css
property to true
.$$css
property is treated as an inline style./* Generated output */
const styles = {
root: {
// Needed by the runtime
$$css: true,
// Debug classes
'debug::file:styles.root': 'debug::file:styles.root',
// Atomic CSS classes
display: 'display-flex-class',
alignItems: 'alignItems-center-class'
}
};
const [ className, inlineStyle ] = styleq(styles.root, props.style);
A factory for creating custom merging functions, tailored to the design of specific compilers.
const compilerStyleq = styleq.factory(options);
Options are used to configure the merging function.
type Options = {
// control memoization
disableCache: boolean = false;
// control className/style merge strategy
disableMix: boolean = false;
// transform individual styles at runtime before merging
transform: ?(style) => compiledStyle;
}
disableCache
Memoization is enabled by default. This option can be used to disable it. Memoization relies on a tree of WeakMaps keyed on static compiled styles. This allows the runtime to efficiently store chunks of merged styles, making re-computation very cheap. However, checking the WeakMap for memoized data when there is none significantly adds to the cost of initially computing the result. Therefore, if initial computations need to be as fast as possible (e.g., your use case involves few repeat merges), memoization should be disabled.
const styleqNoCache = styleq.factory({ disableCache: true });
disableMix
Inline styles are merged together with static styles by default, but can be merged independently if preferred. Both static and inline styles can be passed to styleq
for merging. By default, the properties defined by static and inline styles are merged together. The performance of this option is still excellent, but merging with inline styles often means memoization cannot be used as effectively. In certain circumstances, this merging strategy can actually result in better performance, as the deduplication of styles can reduce the number of CSS rules applied to the element (which improves browser layout times).
If mixing is diabled, the static and inline styles will be treated as values for different attributes: either className
OR style
respectively. If an inline style sets a property that is later set by a static style, both the static class name and dynamic style property will be set. In practice this means that inline style declarations override those of static styles, whatever their position in the styles array passed to styleq
. This means that memoization of class name merges is not precluded by inline styles, and thus provide the best general performance.
const styleqNoMix = styleq.factory({ disableMix: true });
transform
Styles can be transformed before merging by using the transform
function. The runtime loop is extremely performance sensitive as class name merges can happen 1000s of times during a screen render, whether on the server or client. The transform
function is used to change style objects before styleQ merges them. For example, if a compiler needs runtime information before selecting a compiled style.
// compiler/useStyleq
import { styleq } from 'styleq';
import { localizeExtractedStyle } from './localizeExtractedStyle';
import { useLocalization } from './useLocalization'
import { useMemo } from 'react';
export function useStyleq(styles) {
// Runtime context provides subtree writing direction
const { isRTL } = useLocalization();
// Create a custom styleq for i18n transform
const styleqWithPolyfills = useMemo(
() => styleq.factory({
transform(style) {
// Memoize results in the transform
return localizeExtractedStyle(style, isRTL);
}
}),
[ isRTL ]
);
const styleProps = styleqWithPolyfills(styles);
// Add vendor prefixes to inline styles
if (styleProps[1]) {
styleProps[1] = prefixAll(styleProps[1]);
}
return styleProps;
}
WARNING: Transforming compiled styles to support runtime dynamism while retaining excellent performance is possible, however, transforms must be done carefully to avoid creating merge operations that cannot be efficiently memoized. WeakMap
is recommended for memoizing the result of transforms, so that static objects are passed to styleq.
Atomic CSS compilers implementing different styling models can all target styleQ to deliver excellent runtime performance. styleQ can be used at build time and runtime (for server and client) to generate className
and style
values.
Examples of how various compiler features and designs can supported with styleQ are discussed below.
Zero-conflict styles provide developers with guarantees that component style is encapsulated and not impacted by styles defined by other components. A compiler designed around zero-conflict styles will produce smaller CSS style sheets that avoid all specificity and source order conflicts.
Typically, a zero-conflict design involves excluding support for descendant selectors (i.e., any selector that targets an element other than the element receiving the class name). And shortform properties are either disallowed, restricted, or automatically expanded to longform properties. If pseudo-classes (e.g., :focus
) are supported, the compiler must guarantee the order of precedence between pseudo-classes in the CSS style sheet (e.g., :focus
rules appear before :active
rules). If Media Queries are supported, they too must be carefully ordered.
Input:
import * as compiler from 'compiler';
const styles = compiler.create({
root: {
margin: 10,
opacity: 0.7,
':focus': {
opacity: 0.8
},
':active': {
opacity: 1.0
}
}
});
Output:
insertOrExtract('.margin-left-10 { margin-left:10px; }', 0);
insertOrExtract('.margin-top-10 { margin-top:10px; }', 0);
insertOrExtract('.margin-right-10 { margin-right:10px; }', 0);
insertOrExtract('.margin-bottom-10 { margin-bottom:10px; }', 0);
insertOrExtract('.opacity-07 { opacity:0.7; }', 0);
// Pseudo-class insertion order is after class selector rules
insertOrExtract('.focus-opacity-08:focus { opacity:0.8; }', 1.0);
insertOrExtract('.active-opacity-1:active { opacity:1; }', 1.1);
const styles = {
root: {
$$css: true,
marginLeft: 'margin-left-10',
marginTop: 'margin-top-10',
marginRight: 'margin-right-10',
marginBottom: 'margin-bottom-10',
opacity: 'opacity-07',
focus$opacity: 'focus-opacity-08',
active$opacity: 'active-opacity-1'
}
};
The runtime can be used by compilers that support arbitrary selectors, e.g., by concatenating (hashing, etc.) the selector string and property to create a unique key for that selector-property combination. (Note that supporting arbitrary CSS selectors trades flexibility for zero-conflict styles.)
Input:
import * as compiler from 'compiler';
const styles = compiler.create({
root: {
':focus a[data-prop]': {
opacity: 1
}
}
});
Output:
insertOrExtract('.xjrodmsp-opacity-1:focus a[data-prop] { opacity:1.0; }');
const styles = {
root: {
$$css: true,
'xjrodmsp-opacity-1': 'xjrodmsp-opacity-1'
}
};
Atomic CSS has tradeoffs. Once an element has many HTML class names each pointing to different CSS rules, browser layout times slow down. In some cases, compilers may choose to flatten multiple declarations into "traditional" CSS. For example, a component library may optimize the "reset" styles for its core components by flattening those styles, and then inserting those rules in the CSS style sheet before all the atomic CSS. In this case, the Atomic CSS will always override the reset rule but the layout performance of the core components will be significant improved.
Input:
import { createResetStyle } from 'compiler';
function View(props) {
return (
<div {...props} css={reset, props.css} />
);
}
const reset = createResetStyle({
display: 'flex',
alignItems: 'stretch',
flexDirection: 'row',
...
});
Output:
import { styleq } from 'compiler/styleq';
// Compiler inserts Reset CSS rules before Atomic CSS rules.
insertOrExtract('.reset-<hash> { display:flex; align-items:stretch; flex-direction:row', 0);
function View(props) {
const [ className, inlineStyle ] = styleq(reset, props.css);
return (
<div {...props} className={className} style={inlineStyle} />
);
}
const reset = {
$$css: true,
// Compiler decides that only one reset is allowed per element.
// Each reset rule created is set to the '$$reset' key.
$$reset: 'reset-<hash>',
};
A compiler may provide a single API for defining static and dynamic values, and maximize the number of compiled styles by replacing dyanmic values with unique CSS custom properties that are then set by inline styles. This compiler design decouples static and inline property merges, and makes the best use of runtime memoization.
Input:
// @jsx createElement
import { createElement } from 'compiler';
function Fade(props) {
return (
<div
{...props}
css={{
// static value
backgroundColor: 'blue',
// dynamic value
opacity: props.opacity,
...props.css
}}
/>
);
}
Output:
// Custom styleq with mixing disabled
import { customStyleq } from 'compiler/customStyleq';
// The opacity value is a unique CSS custom property
insertOrExtract('.backgroundColor-blue { background-color:blue; }');
insertOrExtract('.opacity-var-xyz { opacity:var(--opacity-xyz); }');
// A compiled style is generated, including the 'opacity' property
const compiledStyle = {
$$css: true,
backgroundColor: 'backgroundColor-blue',
opacity: 'opacity-var-xyz'
};
function Fade(props) {
const [ className, style ] = customStyleq(
// The dynamic value is set to the custom property.
// With static/dynamic mixing disabled, the position of the inline style
// is irrelevant. However, with mixing enabled, the best performance is
// achieved by placing inline styles earlier in the queue.
{ '--opacity-xyz': props.opacity },
compiledStyle,
props.css
);
return (
<div
{...props}
className={className}
style={style}
/>
);
}
Compilers implementing themes using CSS custom properties should avoid creating Atomic CSS rules for each theme property. As mentioned above, this can slow down browser layout and flattening theme styles into a single rule is preferred. Theme classes can be deduplicated by using the same key for all themes in the generated style object.
Input:
import * as compiler from 'compiler';
const [themeVars, themeStyle] = compiler.createDefaultTheme({
color: {
primary: '#fff',
secondary: '#f5d90a'
...
},
space: {},
size: {}
});
const className = compiler.merge(themeStyle, props.style);
Output:
import { styleq } from 'compiler/styleq';
insertOrExtract(
':root, .theme-default { --theme-default-color-primary:#fff; --theme-default-color-secondary:#f5d90a; }'
);
const themeVars = {
color: {
primary: 'var(--theme-default-color-primary)',
secondary: 'var(--theme-default-color-secondary)'
...
}
};
const themeStyle = {
$$css: true,
$$theme: 'theme-default'
};
const [ className ] = styleq(themeStyle, props.style);
A compiler might provide a polyfill for CSS logical properties and values that don't have wide enough native browser support. Using the transform
option is one way to implement this functionality.
Input:
import { StyleSheet } from 'compiler';
function Box() {
return <div style={styles.root} />
}
const styles = StyleSheet.create({
root: {
float: 'inline-start',
}
});
Output:
// See the 'useStyleq' example in the API docs above
import { useStyleq } from 'compiler/useStyleq';
insertOrExtract('.float-left { float:left; }');
insertOrExtract('.float-right { float:right; }');
function Box() {
const [ className ] = useStyleq(styles.view, styles.root);
return <div className={className} />
}
const styles = {
root: {
$$css: true,
// Compiler defines a custom key for the localized transform.
$$transform$i18n: true,
// [ LTR, RTL ]
float: [ 'float-left', 'float-right' ]
}
}
In this case, useStyleq
is a function defined by the compiler which transforms $$css
styles into the correct class name for a given writing direction. An example of this transform can be seen in the localizeStyle
module. Note how care is taken to memoize the transform so that the same result is always used in merges.
Compilers that produce "utility" CSS rules can use styleQ to dedupe utilities across categories, i.e., higher-level styling abstractions such as "size", "spacing", "color scheme", etc. The keys of extracted styles can match the utility categories.
Input:
import { oocss } from 'compiler';
const View = (props) => (
// This compiler targets strings for named "utilities"
<div {...props} className={oocss('cs-1 p-1 s-1', props.css)} />
);
const StyledView = (props) => (
<View {...props} css={oocss('cs-2 p-2')} />
);
Output:
import { styleq } from 'styleq';
insertOrExtract('.cs-1 { --primary-color:#000; --secondary-color:#eee }', 2);
insertOrExtract('.cs-2 { --primary-color:#fff; --secondary-color:#333 }', 2);
insertOrExtract('.p-1 { padding:10px }', 0);
insertOrExtract('.p-2 { padding:20px }', 0);
insertOrExtract('.s-1 { height:100px; width:100px }', 1);
// Each utility class is categorized. For example, only a single 'colorScheme'
// rule will be applied to each element.
const oocss1 = {
$$css: true,
colorScheme: 'cs-1',
padding: 'p-1',
size: 's-1'
};
const View = (props) => (
<div {...props} className={styleq(oocss1, props.css)} />
);
const oocss2 = {
$$css: true,
colorScheme: 'cs-2',
padding: 'p-2'
}
const StyledView = (props) => (
<View {...props} css={oocss2} />
);
styleq is MIT licensed.
FAQs
A quick JavaScript runtime for Atomic CSS compilers.
The npm package styleq receives a total of 493,019 weekly downloads. As such, styleq popularity was classified as popular.
We found that styleq demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.