[RFC] A bunch of similar feature ideas

[nmn]

I wanted to write down a bunch of new but related ideas in a single thread as the APIs make sense as a family. The core idea is to create new optional packages that work without any custom configuration. Importing from and using APIs from these packages would be the explicit signal that you want to use certain features.

Inline Styles

A very long-standing request from the community has been to support some kind of API for defining styles inline. We explored one possible solution to this in #682. https://github.com/nonzzz/stylex-extend

I now think there is a better API we could implement instead:

import * as stylex from '@stylexjs/stylex';
import * as _ from '@stylex/inline-styles';

<div {...stylex.props(
  _.display.flex,
  _.flexDirection.column,
  _.padding._16px,
  _.width['calc(100% - 20cqi)'],
  _.color(color),
)} />

The inline-styles package would export every valid CSS property, but unlike tools like Tailwind, this would not be a "design system". Instead, you'd use actual CSS property names and valid CSS properties with autocomplete support. Additionally:

• A leading underscore will be ignored so it is convenient to use values that start with numbers. i.e. _16px === "16px"
• The normal JS syntax with ["..."] can be used for more complex values that can contain spaces etc.
• Dynamic styles will require calling the property name like a function: _.color(someColorValue).
    - A separate, explicit syntax for dynamic styles ensures that you won't accidentally make static styles dynamic.
    

Known limitations and trade-offs

• We would need to keep the package and types up to date as CSS evolves. There will explicitly be no syntax for defining custom property names
• There is currently no syntax for defining styles that use media queries, pseudo classes etc.

The idea here is that this syntax is not a replacement for stylex.create, but exists as a convenience for simple styles where defining styles with stylex.create feels heavy.

Experimental APIs

We are discussing an experimenal API for theming where defineVars and defineConsts would support "nested namespaces".
Instead of defining these new APIs within the @stylexjs/stylex package, and putting them behind a configuration, we could define them in a new @stylexjs/experimental API:

import * as stylex from '@stylexjs/stylex';
import {defineVars, conditional} from '@stylex/experimental';

export const vars = defineVars({
  fontSize: {
    text: {
      h1: conditional({
        default: '48px',
        '@media (min-width: 768px)': '64px',
      }),
    }
  }
});

Utilities

CSS pre-processors have offered functions like lighten, darken etc for a while. Many of these can be achieved in pure CSS today, but can sometimes feel verbose. We could offer simple utility function that can run like macros before StyleX generates styles:

import * as stylex from '@stylexjs/stylex';
import {opacity, colorMix} from '@stylex/utils';
import {vars} from './myTheme.stylex';

const styles = stylex.create({
  button: {
    backgroundColor: colorMix(vars.accent, 'black', 0.2), // === `color-mix(${vars.accent} 20%, black)`
    boxShadow: `0 4px 4px 2px ${opacity(vars.accent, 0.35)}` // === `0 4px 4px 2px color-mix(${vars.accent} 35%, transparent)`,
    
  }
});

These are just some ideas. We could offer more complex utilities that abstract away CSS tricks such as conditionally applying values using "space hack" with CSS vars.

Additionally, we could allow configuring the Babel plugin to define external packages that should be treated as packages that offer utilities, and we can create a third-party ecosystem of packages that offer "macros" or utilities that can be used during StyleX compilation.

This feature could be used either alongside or instead of the stylex.env. API we’ve discussed before.

Shared Styles

This idea is not fully baked as we need to do a bunch of work to ensure we can mark used vs unused styles and tree-shake styles that are unused, but we could create a way to define styles in third-party packages that can be imported and used and would work just like "internal" styles. I.e. these styles would be eligible for pre-compilation of stylex.props. They would behave the same as if they were defined statically within the same file where they are used.