[CSS-in-JS] Context and foundation #4440

thompsongl · 2021-01-21T19:45:07Z

Summary

Current status: Resolve open questions and decide on timeline

Targeting feature/css-in-js feature branch.

Foundational work for #3912, establishing dependencies, contexts, and initial patterns for

Style generation via CSS-in-JS (Emotion)
- Preferring use of css prop construction over styled-component-like component construction
- Babel-based build accommodation
Theme construction via a Proxy-based system with cascading and computed values
- Proxy-based: allows for the theme system to reference its own values (for reuse or for computational manipulation)
- Cascading: conceptually similar to Sass, where variable location and order are important
- Extendable: allows for appending style variables to the EUI theme structure, scoped to a React context provider
- Override-able: all theme tokens/variables can be altered by consumers
Theme consumption via React hook and HOC methods
Color mode support as first-class consideration
- "Light" and "dark" mode (or defined through extensions/overrides) accounting
- Theme consumption is scoped to the current color mode (set in the context provider)

**Read about the layers of the system**

Unbuilt theme

See euiThemeDefault
An unbuilt theme is a composed object of style values or computed functions.

Style values

Think design tokens or CSS property values. Ready to be consumed as-is in an application environment, using some JavaScript method of applying styles (i.e., emotion is not a requirement).

`computed` functions

These properties specify that the value depends upon some other value in the theme, in the shape of:

computed(
  ['sizes.euiSize'], // dependency array, referencing other properties in the theme object
  ([size]) => size * 2 // predicate. What to do with the dependency values
)

Theme system (built theme)

See EuiThemeDefault
A built theme by way of buildTheme, which transforms the object containing static style values and computed functions into a JavaScript Proxy object with handler traps. In this state, the theme is essentially inaccessible and immutable, that is, it requires getComputed to correctly order and access values and dependencies, and set() is disabled.

Computed theme

See EuiThemeContext
A consumable theme object in which all computed function values have been computed; all values are accessible and usable in an application environment.
Returned from getComputed, in the shape of:

getComputed(
  EuiThemeDefault, // Theme system (Proxy)
  {}, // Overrides object
  'light' // Color mode
)

Overrides

Compute-time value overrides for theme property values. Because a theme system is unchangeable, this mechanism allows for changing values at certain points during consumption.
The overrides object must match the partial shape of the theme system:

{ 
  sizes: {
    euiSize: 4
  }
}

Color mode

Think light and dark mode. A theme has built-in color mode support, using the colors property as a marker:

colors: {
  light: {...}
  dark : {...}
}

getComputed will only compute and return values in the specified current color mode.

**Read about the React-specific context**

EuiThemeProvider

Umbrella provider component that holds the various top-level theme configuration option providers: theme system, color mode, overrides; as well as the primary output provider: computed theme.
The actual computation for computed theme values takes place at this level, where the three inputs are known (theme system, color mode, overrides) and the output (computed theme) can be cached for consumption. Input changes are captured and the output is recomputed.

<EuiThemeProvider
  theme={DefaultEuiTheme}
  colorMode="light
  overrides={{}}
  />

All three props are optional. The default values for EUI will be used in the event that no configuration is provided. Note, however that colorMode switching will require consumers to maintain that app state.

useEuiTheme

A custom React hook that is returns the computed theme. This hook it little more than a wrapper around the useContext hook, accessing three of the top-level providers: computed theme, color mode, and overrides.

const [theme, colorMode, overrides] = useEuiTheme();

WithEuiTheme

A higher-order-component that wraps useEuiTheme for React class components.

Notable components:

EuiThemeProvider: React context provider for theme values and color mode selection
useEuiTheme: theme consumer in React hook form
withEuiTheme: theme consumer in React HOC form (for class components)

~~Notable modifications:~~
* EuiTable*: converted color usage to CSS-in-JS

Miscellaneous:

Snapshot testing (as currently configured) will result in generic emotion-${n} class names with the generated style object as part of the snapshot.
- This seems good for EUI, but it also affects consumers
  - Consumers will need to use the @emotion/jest snapshot serializer to avoid class name churn.
  - Not ideal; unsure of any other solutions
- During the conversion process, the snapshot diffs will look less than ideal when using shallow (a single wrapper element; DOM itself is unchanged):

-                         <div
-                           className="euiTableRowCell__mobileHeader euiTableRowCell--hideForDesktop"
+                         <EmotionCssPropInternal
+                           __EMOTION_LABEL_PLEASE_DO_NOT_USE__="EuiTableRowCell"
+                           __EMOTION_TYPE_PLEASE_DO_NOT_USE__="td"
+                           className="euiTableRowCell"
+                           style={
+                             Object {
+                               "width": undefined,
+                             }
+                           }
                              >

TypeScript support resulting in IDE autocomplete availability when consuming with useEuiTheme
- 🎉
- Extended theme variables can be also be accessed through generic type extensions

Open questions

Do we want to allow EUI styling apart from css prop (e.g. in Kibana)
What works in the css object passed from a project without the babel plugin, e.g.:
object? css={{ textAlign: 'center' }}
import css from eui? css={css`text-align: center`}
EUI does not always apply className to the outermost element, does a css prop on an object prop apply as expected
What do we do with the handful of createElement usages, replace with emotion’s createElement equivalent?
When css is applied on a custom component which element gets the style? What if there's a fragment at the top level?
What component(s) do we want to convert to using Emotion right now, if any? (tables, EuiMark)

Checklist

kibanamachine · 2021-01-21T20:07:43Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-01-22T01:32:55Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-01-26T22:13:51Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-01-28T00:38:04Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-01-28T23:54:12Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-02-03T16:11:23Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-02-05T19:31:45Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-02-05T23:48:43Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

thompsongl · 2021-02-08T19:26:07Z

src/services/theme/theme.ts

+
+// TODO: `calc()` probably not the right solution
+const sizes = {
+  euiSize: '16px',


Based on https://emotion.sh/docs/object-styles#numbers, it's probably best to go unitless.

So, if we move to unitless values:

const styles = css`padding: ${sizes.euiSize}` div css={styles} />

will not automatically add px.

But using div css={{padding: sizes.euiSize}} /> will automatically add px

🤔

To add to that discrepancy, I noticed a funny way the calcs are rendered based on using the css or style tag.

When using the <div css={{}}> syntax it spits out the calc() with the formula intact

When passing as a style tag <div style={{}}> it does the computation and spits out a calc() of the final value.

Yeah the discrepancy is not great. In the latest commit I changed sizes to be unitless, which I like better than using calc.

Although it seems like most folks use strings and just deal with the awkward math because it eliminates any confusion about whether px needs to be added or not.

thompsongl · 2021-02-08T21:01:22Z

What works in the css object passed from a project without the babel plugin, e.g.:

object? css={{ textAlign: 'center' }}

import css from eui? css={csstext-align: center}

Depends on the element type:

EUI components will work with either, regardless of babel plugin/pragma usage
Other elements (native DOM included) will not work with either without babel plugin/pragma usage

~~(Will push some code in a test project that shows this)~~ See https://github.com/thompsongl/cra-eui/tree/ref/emotion

import css from eui?

Haven't really explored this yet, but my first look shows that it might require some extra babel config, which raises questions for CRA/zero-config users.

thompsongl · 2021-02-09T16:52:05Z

src/services/theme/theme.ts

+
+  // Status
+  euiColorSuccess: computed(
+    ['colors.euiColorSecondary'],


I think we'll be able to get autocomplete support for these dependency strings when we upgrade to TS 4.1

This might be a good place for the accessor types. We can take another pass at the strings parsing/completing, but I was unable to get accurate results with that pattern. Maybe instead of computed(...) it could have the shape computed.colors.euiColorSecondary with the proxy accessor, and originating from a custom computed variable would allow detection that it is a computation.

EDIT: still need the computation function, so perhaps computed(euitheme.colors.euiColorSecondary, ...) and not overloading the purpose of euitheme or whatever we call the head of that path.

…ion-poc

kibanamachine · 2021-02-09T21:26:47Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

kibanamachine · 2021-02-10T22:21:38Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

This reverts commit 5614b0f.

thompsongl · 2021-02-16T21:08:39Z

☝️ Cleaner starting point. Set up for TS, testing, linting, etc., but no existing components (or src/ code) have been altered.

kibanamachine · 2021-02-16T21:26:54Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

thompsongl · 2021-02-16T21:54:35Z

jenkins test this

Error: Timed out waiting for: http-get://localhost:9999

kibanamachine · 2021-02-16T22:19:15Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

thompsongl · 2021-02-17T15:37:43Z

jenkins test this

flaky EuiContextMenu

kibanamachine · 2021-02-17T15:59:01Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

chandlerprall

Fantastic foundation to build on!

cchaos

🥇 Great first merge into feature branch. We'll tackle the checklist items as future PR's against the feature branch.

kibanamachine · 2021-02-17T19:22:21Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_4440/

thompsongl · 2021-02-17T19:30:16Z

CI has been pretty unreliable today; merging this as-is into the feature branch. Previous build passed and only change since was a new .md file.

thompsongl added 10 commits January 14, 2021 13:50

poc

26e5f4f

tidy

cdf36a9

Merge branch 'master' into emotion-poc

98244a2

proxy set handler

7e13703

default theme; docs setup

e45fb50

table colors via css-in-js

5614b0f

exports

aa1c2f3

withEuiTheme; useEuiTheme return shape; some types

38e5cf2

export and proxy fixes

da6ae0b

Merge branch 'master' into emotion-poc

455b472

use without provider; some test setup

ada9bd4

prevent unnecessary updates

f7589c1

refactor colorMode calc; move computation to provider

5b6e1cf

thompsongl added 3 commits January 28, 2021 15:58

utils refactor

7ae44fa

Merge branch 'feature/css-in-js' into emotion-poc

3d9ff01

clean up

4648630

thompsongl added 2 commits February 3, 2021 09:40

compute default theme for initial context value

25c70e7

snapshot update preview

66104ab

thompsongl added 4 commits February 3, 2021 10:57

axe ignore temporary docs page

28909a4

theme: colorVis and borders, sizes update

875c86d

Merge branch 'feature/css-in-js' into emotion-poc

0dbbcbe

coupled types

8af54f9

some utils tests

178e176

thompsongl requested review from cchaos and chandlerprall February 8, 2021 18:34

thompsongl marked this pull request as ready for review February 8, 2021 18:34

thompsongl commented Feb 8, 2021

View reviewed changes

thompsongl commented Feb 9, 2021

View reviewed changes

Merge remote-tracking branch '2_upstream/feature/css-in-js' into emot…

d53dba4

…ion-poc

start to amsterdam; name in theme obj

6cefd30

chandlerprall mentioned this pull request Feb 16, 2021

[Meta] CSS-in-JS + theming rollout plan #4529

Closed

10 tasks

thompsongl added 3 commits February 16, 2021 14:43

Merge branch 'feature/css-in-js' into emotion-poc

e0a762a

Revert "table colors via css-in-js"

c84b4ee

This reverts commit 5614b0f.

eslintrc

18fcd48

chandlerprall approved these changes Feb 17, 2021

View reviewed changes

cchaos approved these changes Feb 17, 2021

View reviewed changes

readme

760aea8

thompsongl merged commit 156f7fe into elastic:feature/css-in-js Feb 17, 2021

thompsongl mentioned this pull request Jul 30, 2021

[Meta][CSS-in-JS] Switching to emotion #3912

Open

24 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CSS-in-JS] Context and foundation #4440

[CSS-in-JS] Context and foundation #4440

thompsongl commented Jan 21, 2021 •

edited

Loading

kibanamachine commented Jan 21, 2021

kibanamachine commented Jan 22, 2021

kibanamachine commented Jan 26, 2021

kibanamachine commented Jan 28, 2021

kibanamachine commented Jan 28, 2021

kibanamachine commented Feb 3, 2021

kibanamachine commented Feb 5, 2021

kibanamachine commented Feb 5, 2021

thompsongl Feb 8, 2021

thompsongl Feb 10, 2021 •

edited

Loading

cchaos Feb 10, 2021

thompsongl Feb 11, 2021

thompsongl Feb 11, 2021

thompsongl commented Feb 8, 2021 •

edited

Loading

thompsongl Feb 9, 2021

chandlerprall Feb 9, 2021 •

edited

Loading

kibanamachine commented Feb 9, 2021

kibanamachine commented Feb 10, 2021

thompsongl commented Feb 16, 2021

kibanamachine commented Feb 16, 2021

thompsongl commented Feb 16, 2021

kibanamachine commented Feb 16, 2021

thompsongl commented Feb 17, 2021

kibanamachine commented Feb 17, 2021

chandlerprall left a comment

cchaos left a comment

kibanamachine commented Feb 17, 2021

thompsongl commented Feb 17, 2021

[CSS-in-JS] Context and foundation #4440

[CSS-in-JS] Context and foundation #4440

Conversation

thompsongl commented Jan 21, 2021 • edited Loading

Summary

Unbuilt theme

Style values

computed functions

Theme system (built theme)

Computed theme

Overrides

Color mode

EuiThemeProvider

useEuiTheme

WithEuiTheme

Open questions

Checklist

kibanamachine commented Jan 21, 2021

kibanamachine commented Jan 22, 2021

kibanamachine commented Jan 26, 2021

kibanamachine commented Jan 28, 2021

kibanamachine commented Jan 28, 2021

kibanamachine commented Feb 3, 2021

kibanamachine commented Feb 5, 2021

kibanamachine commented Feb 5, 2021

thompsongl Feb 8, 2021

Choose a reason for hiding this comment

thompsongl Feb 10, 2021 • edited Loading

Choose a reason for hiding this comment

cchaos Feb 10, 2021

Choose a reason for hiding this comment

thompsongl Feb 11, 2021

Choose a reason for hiding this comment

thompsongl Feb 11, 2021

Choose a reason for hiding this comment

thompsongl commented Feb 8, 2021 • edited Loading

thompsongl Feb 9, 2021

Choose a reason for hiding this comment

chandlerprall Feb 9, 2021 • edited Loading

Choose a reason for hiding this comment

kibanamachine commented Feb 9, 2021

kibanamachine commented Feb 10, 2021

thompsongl commented Feb 16, 2021

kibanamachine commented Feb 16, 2021

thompsongl commented Feb 16, 2021

kibanamachine commented Feb 16, 2021

thompsongl commented Feb 17, 2021

kibanamachine commented Feb 17, 2021

chandlerprall left a comment

Choose a reason for hiding this comment

cchaos left a comment

Choose a reason for hiding this comment

kibanamachine commented Feb 17, 2021

thompsongl commented Feb 17, 2021

thompsongl commented Jan 21, 2021 •

edited

Loading

`computed` functions

thompsongl Feb 10, 2021 •

edited

Loading

thompsongl commented Feb 8, 2021 •

edited

Loading

chandlerprall Feb 9, 2021 •

edited

Loading