Atm the build will fail if theres no new code to deploy. Ideally we should check before publishing if the version will be different - and then publish it!

Emotion

Input:

{
  content: '"😎"'
}

Compiles to CSS:

content: '😎';

Styled components

Input:

{
  content: '😎'
}

Compiles to CSS:

content: '😎';

I'm pretty sure https://github.com/danieldelcore/trousers has the best API among all other css-in-js interfaces.

Any plans to use something as cool as it, rather that something not cool (...as usual)

cc @danieldelcore

https://www.styled-components.com/docs/api#withcomponent

API

We will standardize on the @emotion/react API:

import { Global } from '@compiled/react';

<Global 
  styles={{
    h1: { fontSize: 30 }
  }}
/>

Assumptions

• Dynamic declarations can't work with global styles
• Global styles will be extracted to an external stylesheet

Outstanding questions

• Do we force @font-face declarations to go through this component? Currently they can't be defined anywhere because it will blow up in prod mode
• How can we conditionally set global styles when they have been extracted to an external stylesheet? If there is no good story for this we may need to just not support this when baked as well.

right now we are defining class names and css variables sequentially:

.a
.b
.c
...
.aa
.ab

and for css variables its a little better:

// every variable has a unique sequential id concat with its identifier name
--color-a
--textSize-b
...
--margin-aa

We want to have a balance of size to uniqueness to avoid clashes.

Either namespacing them (so every pkg gets it own namespace) - OR hashing - would be the most ideal.

We can really only get away with naming things sequentially if we have all the information - which we don't in a component library. Maybe we can introduce another transformer to do a pass for our consumers?

Options

• introduce namespacing
• introduce hashing for the component name
• introduce hashing for the content (ala how most css in js do it)
• ??

We are going to have a few packages - we should probably move over to a mono repo sooner rather than later

/packages
  /ts-transformer
  /css-in-js
  /jest

will also allow us to build ts-transformer for node and css-in-js for browsers. needs a bit more thoughts tho.

Currently if you do this:

<div css={{ fontSize: 12 }} />

It'll resolve to:

font-size: 12 

It should resolve to:

font-size: 12px

Should work for all APIs.

Confirmed here the behaviour for emotion and styled: https://codesandbox.io/s/youthful-bardeen-qtjfb

https://github.com/madou/untitled-css-in-js-project/blob/master/src/ts-transformer/class-names/__tests__/index.test.tsx#L46

There are already test TODOs waiting for you - pick up any that look interesting. Just jump in write the test first and then jump into the implementation - there might also be test cases I've missed so if you think of any please add them 👍

• static
• referencing string variable inside module
• referencing number variable inside module
• referencing object variable inside module
• referencing array variable inside module
• referencing function call expression inside module (no args)
• referencing function call expression inside module (with args)
• referencing string variable import
• referencing number variable import
• referencing object variable import
• referencing array variable import
• referencing function call expression import (no args)
• referencing function call expression import (with args)

https://github.com/madou/untitled-css-in-js-project/blob/master/src/ts-transformer/css-prop/__tests__/index.test.tsx#L64

There are already test TODOs waiting for you - pick up any that look interesting. Just jump in write the test first and then jump into the implementation - there might also be test cases I've missed so if you think of any please add them 👍

• static string
• static template string
• referencing string variable inside module
• referencing number variable inside module
• referencing object variable inside module
• referencing array variable inside module
• referencing function call expression inside module (no args)
• referencing function call expression inside module (with args)
• referencing string variable import
• referencing number variable import
• referencing object variable import
• referencing array variable import
• referencing function call expression import (no args)
• referencing function call expression import (with args)

So take this code:

const Container = styled.div`
  color: ${props => props.primaryColor}; // will be destructured
  width: ${props => props.width}; // will not be destructured because its a valid attribute
`;

Should generate:

const Container = ({ primaryColor, ...props  }) => (
  <>
    <style>{`.a { color: var(--primary-color-a); width: var(--width-b) }`}</style>
    <div style={{ '--primary-color-a': primaryColor, '--width-a': props.width }} {...props}>{props.children}</div>
  </>
);

• run npm version locally to build tags and push to git
• on tagged commits run npm deploy

etc

16px -> 1rem

cc @danieldelcore

const fadeIn = keyframes({
  from: { opacity: 0 },
  to: { opacity: 1 },
});

export const fadeIn = {
  name: 'keyframes-a',
  keyframes: `
    from: { opacity: 0; }
    to: { opacity: 1; }
  `,
  variables: {},
};

import { fadeIn } from './fade-in';

<div css={{ animation: fadeIn }}>
  hello world
</div>

import { fadeIn } from './fade-in';

<>
  <style>
    {`
      @keyframes ${fadeIn.name} {
        ${fadeIn.keyframes}
      }

      .a { animation: ${fadeIn.name} }
    `}
  </style>
  <div className="a">
    hello world
  </div>
</>

export const fadeIn = (props) => keyframes({
  from: { opacity: 0 },
  '50%': { color: props.color },
  to: { opacity: 1 },
});

export const fadeIn = (props) => ({
  name: 'keyframes-a',
  keyframes: `
    from: { opacity: 0; }
    50%: { color: var(--color-a); }
    to: { opacity: 1; }
  `,
  variables: { '--color-a': props.color },
});

import { fadeIn } from './fade-in';

const Component = props =>
<div css={{ animation: fadeIn({ color: props.color }) }}>
  hello world
</div>

import { fadeIn } from './fade-in';

const Component = props => {
  const keyFramesA = fadeIn({ color: props.color });

  return <>
    <style>
      {`
        @keyframes ${keyFramesA.name} {
          ${keyFramesA.keyframes}
        }

        .a { animation: ${keyFramesA.name} }
      `}
    </style>
    <div style={keyFramesA.variables} className="a">
      hello world
    </div>
  </>
};

First pass will be hashing animation keyframes name and then only being able to use them locally.

<div
  css={`
    @keyframes fade-in {
      from { opacity: 0 }
      to { opacity: 1 }
    }

    animation: fade-in;
  `}
/>

To:

@keyframes cc-abc123 {
  from { opacity: 0 }
  to { opacity: 1 }
}

.cc-abc123 {
  animation: cc-abc123;
}

Fixed

class name generation is counting A different to a - but as far as class names are concerned they're the same thing.

• fixed in #63

class names that result from a transform can be cached and the whole premise doesn't work so we have duplicate class names being used

<div class="b">
<h2 class="b">

• fixed in #63

import { heroBackground } from '../utils/colors';

const Hero = styled.div({
  height: '80vh',
  backgroundColor: heroBackground,
});

css variable isn't set

• fixed

import { heroBackground } from '../utils/colors';

const Hero = styled.div`
  background-color: ${heroBackground},
`;

blows up with declaration does not exist

• not a bug - parcel has type checking turned off so the result of typeChecker.getSymbolAtLocation(node.moduleSpecifier); is always undefined. need to figure out what to do about this.

looking at this in #66

Needs fixing

React is undefined when creating css prop or styled component.

• to fix in #55

css prop on closed element

<div css={{}} />

exhausts stack

• fixed

css prop tagged template

<div css={{ color: `yo` }}></div>

unsupported

• fixed

export const Header = styled.header`
  height: 8rem;
  display: flex;
  align-items: center;
  background-color: #091f41;
  padding: 0 2rem;
  color: white;
`;

export const FixedHeader = (props: any) => (
  <>
    <div css={{ height: '8rem' }} />
    <FixedHeader {...props} />
  </>
);

infinite loop

• fixed

class name doesn't get conditionally applied

  <pre
    className={props.className}
    css={{}}></pre>

where className is undefined results in class="f undefined"

• fixed

Style gets added multiple times to the same import

/Users/madou/projects/website/src/pages/root.tsx:14:16: Identifier 'Style' has already been declared (14:16)

• fixed

If we've gotten this to a state where its faster, better, and we have decided we want to go ahead with consuming this in Atlaskit we'll then progress to these.

Phase 2 - feature completeness

• improve developer experience/enrich error messages/constraints
• investigate theming API
• add babel plugin support
• keyframes #14
• mixins #17
• theming #18
• runtime evaluated variables #28

Phase 3 - UNLIMITED POWER

• new transformer to extract compiled css to a file(s) vs. #36
• new transformer that can run over all of your compiled css to "atomic-ify" it
• see if we need a small runtime to move style tags to the document head

Inside ast-node.tsx we have a function createNodeError().

We need to update it so the error thrown points directly to the node in question and tells them exactly what they need to do to fix the problem.

Something like:

<div
  css={{
    ...funcThatIsTooDynamic(),
     ☝️  function is too dynamic and is impossible to statically analyze.
  }}
/>

Currently they're all "Anonymous".

Should be only done in dev.

See: microsoft/TypeScript#35686

https://github.com/madou/untitled-css-in-js-project/blob/master/src/ts-transformer/styled-component/__tests__/index.test.tsx#L50

There are already test TODOs waiting for you - pick up any that look interesting. Just jump in write the test first and then jump into the implementation - there might also be test cases I've missed so if you think of any please add them 👍

• static template string
• referencing string variable inside module
• referencing number variable inside module
• referencing object variable inside module
• referencing array variable inside module
• referencing function call expression inside module (no args)
• referencing function call expression inside module (with args)
• referencing string variable import
• referencing number variable import
• referencing object variable import
• referencing array variable import
• referencing function call expression import (no args)
• referencing function call expression import (with args)

Currently you can compose CSS if:

1. It is variable is statically analyzable to be CSS like
2. Accept that the style will be inlined into the compiled component (multiple uses of composing = multiple declarations - gzip would make this w/e I suppose but it's still more code to execute!)

And you can do it via module boundaries if:

1. Typechecking with TypeScript is turned on (this means it doesn't work if it's off, and it doesn't work if you're compiling with Babel, issue to make it better here #66)

Use case is to transform variable declarations and then re-use them as variables instead of always inlining them into the style tags. I want to lean on the name mixin over css because this does not, and will never, return a className. css is overloaded in other css-in-js libraries to return a form of className.

Transforms:

const borderColor = 'black';

const myMixin = (props) => mixin({
  border: `1px solid ${borderColor}`,
  color: props.color,
});

// mixin return type is the input object

To:

const myMixin = (props) => ({
  variables: { '--color-a': props.color },
  css: `
    border: 1px solid black; /* variable isnt in the closure so it gets compiled in */
    color: var(--color-a); /* variable was in closure so it gets xformed to a css var */
  `
});

...which then can be reused in components

From:

import { myMixin } from './mixins';

const MyDiv = (props) => (
  <div css={{ '&': myMixin({ color: props.color })  }}>
    hello world
  </div>
);

To:

import { myMixin } from './mixins';

const MyDiv = (props) => {
  const mixin = myMixin({ color: props.color });

  return (
    <>
      <style>{`.a { ${mixin.css} }`}</style>
      <div style={mixin.variables} className="a">hello world</div>
    </>
);

Edit: Update 6/Oct/2020

Because we've pivoted to atomic CSS things now are made more complicated. We still however need to maintain this story.

A note on design decisions - Right now Compileds primary goal is to introduce constraints that make it impossible to write unperformant CSS in JS.
If we can solve the 90% here that is good enough.

Currently we operate essentially the same as Emotion's default config.

SSR rendered markup:

<style>...</style>
<div class="abc">...</div>

Client markup:

<head>
  <style>...</style>
</head>
..
<div class="abc">...</div>

While this means SSR is 0 config and it just works (with streaming as a bonus) - it makes using any nth selectors annoying/shitty to use.

:first-child
:nth-child
:nth-of-type
:nth-last-of-type
:nth-last-child
:first-of-type
:last-child
* + *

I really want to solve this without re-architecting how things work for the default implementation.
We need to investigate if we can do some CSS magic to create equivalent selectors for the 90% case that:

1. works for ssr before js has executed (style before the component atm)
2. works for client after js has executed (style in the head now)

Remember: The style element will move when JS executes. We need to handle both states.

Right now we can use it like this:

expect(getByText('hello world')).toHaveCompiledCss('font-size', '15px');

Would be great it we could..

expect(getByText('hello world')).toHaveCompiledCss({
  fontSize: '15px',
  color: 'red',
});

Use https://github.com/atlassian-labs/storybook-addon-performance

https://github.com/madou/untitled-css-in-js-project/blob/master/src/ts-transformer/css-prop/__tests__/index.test.tsx#L129

There are already test TODOs waiting for you - pick up any that look interesting. Just jump in write the test first and then jump into the implementation - there might also be test cases I've missed so if you think of any please add them 👍

• static string
• static template string
• referencing string variable inside module
• referencing number variable inside module
• referencing object variable inside module
• referencing object variable inside module that is spread into css prop
• referencing array variable inside module
• referencing function call expression inside module (no args)
• referencing function call expression inside module (with args)
• referencing string variable import
• referencing number variable import
• referencing object variable import
• referencing array variable import
• referencing function call expression import (no args)
• referencing function call expression import (with args)

Compiles (it would be createElement though instead of jsx)

// component.tsx
<>
  <style>.a { font-size: 10px; }</style>
  <div class="a">...</div>
</>

To

// component.tsx
import './component.css';
<div class="a">...</div>

// component.css
.a { font-size: 10px; }

• Css extraction and the like can be left in user land.
• Need to be a bundler plugin (Webpack & Parcel)

https://github.com/madou/untitled-css-in-js-project/blob/master/src/ts-transformer/class-names/__tests__/index.test.tsx#L78

There are already test TODOs waiting for you - pick up any that look interesting. Just jump in write the test first and then jump into the implementation - there might also be test cases I've missed so if you think of any please add them 👍

• static
• referencing string variable inside module
• referencing number variable inside module
• referencing object variable inside module
• referencing array variable inside module
• referencing function call expression inside module (no args)
• referencing function call expression inside module (with args)
• referencing string variable import
• referencing number variable import
• referencing object variable import
• referencing array variable import
• referencing function call expression import (no args)
• referencing function call expression import (with args)

const StyledDiv = styled.div<{ fontSize: number }>`
  font-size: ${props => props.fontSize}px;
`;

That px shouldn't be in the final css

https://www.styled-components.com/docs/api#attrs

See test in packages/ts-transform/src/__tests__/index.test.tsx

Right now we will inline every constant value (string, number, object) - however it may also be beneficial to allow consumers to use a function that returns a simple constant value (string, number).

<div
  css={{
    height: () => document.offsetHeight
  }} 
/>

<>
  <style>.a { height: var(--a) }</style>
  <div style={{ '--a': (() => document.offsetHeight)() }} />
</>

👍

Should also handle function references:

<div
  css={{
    height: someOtherFunction
  }} 
/>

<>
  <style>.a { height: var(--a) }</style>
  <div style={{ '--a': someOtherFunction() }} />
</>

This should be pretty easy thanks to typescript 😄

Need to figure out how this would apply with a styled component - because they can already use functions to define props. Would a function that returns a function be weird?

I think having an org from the start is a better idea. I have all of these

• @compiled/css-in-js 👈 fav atm. it's literally what it is
• @compiled/css
• @puck-pkg/css
• @compiled-css/core

function mixin() {
  return {};
}

• spread no args ...mixin()
• spread with args ...mixin(color)
• assignment no args color: mixin()
• assignment with args color: mixin(color)

Smaller the better

Thinking something like replacing the <style> element we add for every component with an equivalent custom component.

const Style = (props) => {
  if (/* on the client */ && /* not yet in head */) {
    /* add styles to head */
    return null;
  }

  /* on the server */
  return <style data-compiled-id={props.id}>{props.children}</style>;
};

• should not add if its already there
• should only do the calculation once - if it re-renders do nothing
• should render style element on the server
• should be as small and fast as possible
• need to figure out what to do with the whole "no runtime" thing since this breaks it - but it's kind of needed
• should be FAST - probably needs to use the same browser APIs that styled/emotion use
• needs to be able to be removed via a transformer

Inspiration points:

• https://github.com/emotion-js/emotion/tree/master/packages/sheet
• https://github.com/styled-components/styled-components/blob/master/packages/styled-components/src/sheet/Rehydration.js#L55
• https://github.com/emotion-js/emotion/blob/master/packages/utils/src/index.js#L23
• https://github.com/emotion-js/emotion/blob/master/packages/cache/src/index.js#L71

https://github.com/madou/untitled-css-in-js-project/blob/master/src/ts-transformer/styled-component/__tests__/index.test.tsx#L84

There are already test TODOs waiting for you - pick up any that look interesting. Just jump in write the test first and then jump into the implementation - there might also be test cases I've missed so if you think of any please add them 👍

• static object
• referencing string variable inside module
• referencing number variable inside module
• referencing object variable inside module
• referencing array variable inside module
• function call to create prop on component
• referencing function call expression inside module (no args)
• referencing function call expression inside module (with args)
• referencing string variable import
• referencing number variable import
• referencing object variable import
• referencing array variable import
• referencing function call expression import (no args)
• referencing function call expression import (with args)

pls someone

Fresh eyes needed. We should also take inspiration from https://theme-ui.com/

We can even create a TS language service to tell us what themes are available with intellisense!

Global theming

Define your tokens in your options:

{
  base: {},
  default: {},
  [optionalotherthemes]: {} // every other theme needs to have the same keys from default
}

Then use them in your CSS sourced from default:

css`
  color: primary; // or
  color: theme(primary);
`

Transforms to:

color: #fff;
color: var(--var-123abc);

Hardcodes and use the variable so it works with/without a parent theme.

Prepare a theme provider for consumers (you should only ever create one of these):

import { createThemeProvider } from '@compiled/css-in-js';

export const ThemeProvider = createThemeProvider();

// Optional "runtime" themes.
export const ThemeProvider = createThemeProvider({ ... });

Transforms to:

import { _TP } from '@compiled/css-in-js';

const theme = { base: { ... }, default: { '--var-abc123': '#000', ... }, ... };
// optional runtime themes would be merged in and converted to css variables

export const ThemeProvider = (props) => (
  <_TP theme={props.theme}>
   {props.children(theme[props.mode])
  <_TP>
);

And then your consumers use like:

import { ThemeProvider } from 'your-design-system';

const App = () => (
  <ThemeProvider theme="dark">
     {style => <div style={style}>...</div>
  </ThemeProvider>
);

Component theming

Would be the same as above with one key difference - the theme isn't sourced from the config. It's sourced inline.

import { createVariants } from '@compiled/css-in-js';

const useVariants = createVariants<'primary' | 'danger'>({
  default: { default: {}, [optionalotherthemes]: {} },
  [optionalotherthemes]: {},
});

<button style={useVariants('primary')} css={{ border: 'border', color: 'color' }}>
  blah
</button>

import { useMode } from '@compiled/style;

// transformed to css variables
const variants = { default: {}, ... };

const useVariants = (variant: string) => {
  const mode = useMode();
  const defaultVariant = variants.default;

  return { 
    ...defaultVariant.default,
    ...defaultVariant[mode],
    ...variants[variant][mode],
  };
};

The type safety aspect is missing a little. Perhaps instead of using string literals theme(primary) and variant(color) we could import them?

import { themeRefs, createVariants } from '@compiled/css-in-js'; 

const { useVariants, variant } = createVariants({});
const theme = themeRefs();

<div
  style={useVariants('primary')}
  css={{
    backgroundColor: variant('backgroundColor'),
    color: theme('primary'),
  }}
/>

???

Goals

• Minimal use of react context
• Css variables for passing style values around
• Don't force specific markup to consumers
• Ensure bleeding of css variables doesn't affect things it shouldn't

Lingering thoughts

• What about runtime themes (i.e. they aren't known until runtime)?

See: #22

It's blowing up when iterating through the JSX attributes (className doesn't have a parent = blows up).

Need to understand why - if it's a bug - and if we can work around it. It works fine in tests - blows up when running storybook/webpack/ts-loader though.

Found this https://github.com/longlho/ts-transform-css-modules - should be good reference.

Edit: Or not because it follows css files not typescript. Meh.

Edit: Let's target just using it in the same module for now. 👍

At the same time I wonder if this is really needed or if we should just say use data attributes instead.

The overhead would be to add some kind of identifier to every styled component as a class.

const Child = styled.li``;

const Container = styled.ul`
  ${Child} {
    margin-left: 20px;
  }
`;

const Child = styled.li``;

const Container = styled.ul({
  [Child]: {
    marginLeft: '20px',
  }
});

// #ccid=cc-idhash1 <-- place this so we don't have to traverse to extract
const Child = props => (
  <>
    <Style>[]</Style>
    <div {...props} className="cc-idhash1 cc-hash" />
  </>
)

const Container = props => (
  <>
    <Style>['.cc-idhash1 { margin-left: 20px; }']</Style>
    <div {...props} className="cc-idhash2 cc-hash" />
  </>
)

The tests are already defined someone just needs to go in, write them, and see if they pass.

Main point is to do a pass over their own components + node modules dependencies that are using compiled components and then to extract them to a single, atomic, css sheet.

This would need to be a bundler plugin. Webpack & Parcel.

The idea:

• You have a component library, let's call it @catlaskit
• You have a product, let's call it Gira
• Product Gira uses compiled components from @catlaskit
• Product Gira also defines its own compiled components
• We'd write this plugin to parse ALL compiled components (from both @catlaskit and Gira, and really anywhere) so when Gira builds their bundle - it extracts ALL compiled components to a CSS file
• We would want to build it in such a way so if there were cases it would report failures but not fail the build.

Cool right?

run tests, build, etc

• array from import (object css)
• array from local variable (object css)
• array from import (template literal css)
• array from local variable (template literal css)

We will probably just release under a random name initially to start testing this internally at Atlassian. Other than that we have a few things to do for the first phase of the library.

We've made it work from the spike and proven this can work. Now it's about getting it in a state that can be used in production for Atlaskit.

• decide package name
• css api all tests pass
• styled api all tests pass
• class names api all tests pass
• prefix transformer option for class/css-variables
• const blowing up bug fixed see microsoft/TypeScript#35686
• performance benchmarking

In @compiled/css-in-js

Every time we version bump it should bump its version too. if we don't fix this we get into weird upgrade pains like seen in the website.

https://www.styled-components.com/docs/api#as-polymorphic-prop

We already support template literals. Only needed in object api since you don't really need this in template literal api.

const ListItem = styled.div({
  fontSize: props => props.fontSize + 'px',
});