[Meta][CSS-in-JS] Component conversions

[thompsongl]

Wiki Doc for How to Write Styles with Emotion

Completed

• Accordion (EuiAccordion convert Sass to Emotion CSS #5826) @1Copenut
• Bottom bar @breehall [Emotion] Convert EuiBottomBar to Emotion #5823
• Flex @constancecchen [Emotion] Convert EuiFlexGroup, EuiFlexItem, and EuiFlexGrid #6270
• Flyout @breehall [Emotion] Convert EuiFlyout #6213
• Horizontal rule ([EuiHorizontalRule] convert horizontal rule to emotion #5815)
• Page @cchaos
• Page header @cchaos
• Panel @cchaos [Emotion] Convert EuiPanel #5891
• Popover @cchaos [EuiPopover and parts] Converted to Emotion #5977
• Spacer ([EuiSpacer] Converts EuiSpacer to Emotion #5812)
• Button
  • [EuiButton] Convert to Emotion #5989
  • [Emotion] Convert EuiButton #6150
• Facet @miukimiu ([Emotion] Convert EuiFacetButton and EuiFacetGroup #5878)
• Link ([Emotion] Convert EuiLink #5856) @MichaelMarcialis
• Pagination [EuiPagination & Co.] Convert to Emotion styling #6109
• Tabs [Emotion] EuiTabs #6311
• Aspect ratio ([EuiAspectRatio] Remove sass and replace with inline styles #5818)
• Avatar ([CSS-in-JS] Convert EuiAvatar #5670)
• Badge ([Emotion] Convert EuiBadge #6224, [Emotion] Convert EuiBadgeGroup, EuiBetaBadge, and EuiNotificationBadge  #6258)
• Callout @cchaos [Emotion] Convert EuiCallOut #5870
• Card [EuiCard & friends] Convert to Emotion #6110
• Comment list @miukimiu ([EuiComment] Add "custom" option to EuiComment.type and more enhancements #5692)
• Description list @breehall [Emotion] Convert EuiDescriptionList #5971
• Health @constancecchen [Emotion] Convert EuiHealth #5832
• Icons @miukimiu [Emotion] Convert EuiIcon #5967
• Token @miukimiu [Emotion] Convert EuiToken #6067
• Image @miukimiu [Emotion] Convert EuiImage #5969
• List group @miukimiu [Emotion] Convert EuiListGroup #6207
• Loading @cchaos [Emotion] Convert the rest of the Loading components #5845
  • Loading Chart ([Emotion] Converted EuiLoadingChart #5821) @cchaos
• Progress @constancecchen [Emotion] Convert EuiProgress #5986
• Range sliders @miukimiu [Feature Branch] Convert EuiRange sliders to Emotion and more enhancements  #6092
• Stat @constancecchen [Emotion] Convert EuiStat #5968
• Text @constancecchen [Emotion] Convert EuiText, EuiTextAlign, and EuiTextColor #5895
• Title @constancecchen [Emotion] Convert EuiTitle  #5842
• Toast [EuiToast & Co.] Convert to function component, Emotion styling #6068
• Tooltip [EuiToolTip] Convert to Emotion styling #6104
• Tour [EuiTour] Convert to Emotion styling #6087
• Code @miukimiu [Emotion] Convert EuiCode and EuiCodeBlock #6263
• [Emotion] EuiModal #6403 @miukimiu ([Emotion] Convert EuiModal #6321)

Utilities

• Accessibility
  • Screen reader only [CSS-in-JS] Convert EuiScreenReaderOnly #5846
  • Skip link [CSS-in-JS] Convert EuiSkipLink #5851
• Beacon @miukimiu ([Emotion] Converted EuiBeacon #5814)
• CSS utility classes [Emotion] Convert global className utilities #6124
• Error boundary [CSS-in-JS] Convert EuiErrorBoundary #6053
• Highlight and mark ([CSS-in-JS] Convert EuiMark #4575)
• Overlay mask [EuiOverlayMask] Convert to Emotion; remove onClick prop #6090
• Portal [Emotion] Convert EuiPortal #6075
• Text diff [CSS-in-JS] Convert EuiTextDiff #6056

Partially complete

Beta Give feedback

1. [Emotion] EuiButton #6388
   emotion task +2
   
2. [Emotion] EuiKeyPadMenu (EuiKeyPadMenuItem Component Only 2/2) #6653
   emotion task +2
   
3. [Emotion] EuiAccordion #6386
   emotion task +2
   
4. [Emotion] EuiResizableContainer #6408
   emotion task +2
   
5. [Emotion] EuiSplitPanel #6406
   emotion task +2
   

Display

Beta Give feedback

1. [Emotion] EuiNotificationEvent #6404
   emotion task +2
2. [Emotion] EuiEmptyPrompt #6397
   emotion task +2
   
3. [Emotion] EuiDragAndDrop #6396
   emotion task +2
   

Navigation

Beta Give feedback

1. [Emotion] EuiCollapsibleNav #6389
   emotion task +2
   
2. [Emotion] EuiContextMenu #6392
   emotion task +2
   
3. [Emotion] EuiControlBar #6393
   emotion task +2
4. [Emotion] EuiSideNav #6412
   emotion task +2
   
5. [Emotion] EuiTreeView #6416
   emotion task +2
   
6. [Emotion] EuiKeyPadMenu (EuiKeyPadMenu Component Only 1/2) #6401
   emotion +1
   
7. [Emotion] EuiSteps #6413
   emotion +1
   
8. [Emotion] EuiBreadcrumbs #6418
   emotion +1
   

Layout

Beta Give feedback

1. [Emotion] EuiHeader #6417
   emotion task +2
   
2. [Emotion] EuiPage #6405
   emotion task +2

Tables

Beta Give feedback

1. [Emotion] EuiTable #6415
   emotion task +2
   
2. [Emotion] EuiBasicTable #6387
   emotion task +2

Forms

Beta Give feedback

1. [Emotion] EuiFilterGroup #6398
   emotion task +2
   
2. [Emotion] EuiSearchBar #6410
   emotion task +2
   
3. [Emotion] EuiSelectable #6411
   emotion task +2
4. [Emotion] EuiComboBox #6391
   emotion task +2
5. [Emotion] EuiColorPicker #6390
   emotion task +2
6. [Emotion] Forms #6400
   emotion task +2
   

Low priority (3rd party components or components that may move out of EUI)

Beta Give feedback

1. [Emotion] EuiDatePicker #6395
   emotion task +2
2. [Emotion] EuiMarkdownEditor #6402
   emotion task +2
   
3. [Emotion] EuiDataGrid #6394
   emotion task +2
4. [Emotion] EuiSuggest #6414
   emotion task +2

Docs

Beta Give feedback

1. Guide page
2. Guide rule
3. Guide section

[breehall]

Component Conversion Process

Converting the Sass styles to Emotion

1. New file structure

• In the component directory (in src/components/{component} ), create a new file for Emotion styling. Files should follow the {component}.styles.ts naming structure (i.e avatar.styles.ts). In this file, convert the existing Sass styles to Emotion. For detailed information on converting styles, formatting styles, and creating style helpers, see writing styles with Emotion. For more detailed conversion checklist see comment below.
• Import the new Emotion style file into the component ({component}.tsx). Import useEuiTheme() from the services directory and configure the component to use Emotion styling.

Example

//imports
import { useEuiTheme } from '../../services';
import { euiAvatarStyles } from './avatar.styles';

//set the theme and configure Emotion styling
const euiTheme = useEuiTheme();
const styles = euiAvatarStyles(euiTheme);

• Downstream components that take mounted snapshots including the converted component may see some <Insertion> component shenanigans. These snapshots should be addressed by one of the following options:
  • Converting mount() to render()
  • Converting mount() to mount().render()
  • Avoid taking a snapshot and instead using a more specific assertion, depending on the test (e.g. if a specific component is supposed to be present)

2a. Convert & Remove Sass component styles

• Move the Sass styles into the newly created {component}.styles.ts
• Remove the Sass modules and stylesheets found in the component directory (in src/components/{component} ). This should include the stylesheets and the_index.scss file found in the component folder. In src/components/index.scss, remove the import for the component Sass module

2b. Update style props types by removing classNameMaps where possible

See #5889 for examples.

If the modifier piece of the class name --{modifier} is the same string as the possible prop values, switch to applying the modifier piece of the class name directly as they key. Remove the manual maps of property value to class name maps and change the array of values as an exported array as const.

Example:

const sizeToClassNameMap = {
  s: 'euiAvatar--s',
  m: 'euiAvatar--m',
  l: 'euiAvatar--l',
  xl: 'euiAvatar--xl',
};

export const SIZES = keysOf(sizeToClassNameMap);
export type EuiAvatarSize = keyof typeof sizeToClassNameMap;

const classes = classNames(
  'euiAvatar',
  sizeToClassNameMap[size],
);

Becomes:

export const SIZES = ['s', 'm', 'l', 'xl'] as const;
export type EuiAvatarSize = typeof SIZES[number];

const classes = classNames(
  'euiAvatar',
  {
    [`euiAvatar--${size}`]: size,
  },
);

If they don't match completely 1:1, you will need to keep the map, but remove the euiComponentName-- part of the value and still apply the className directly in the function:

export const MARGINS = ['none', 'xs', 's', 'm', 'l', 'xl', 'xxl'] as const;
export type EuiHorizontalRuleMargin = typeof MARGINS[number];

const marginToClassNameMap: {
  [value in EuiHorizontalRuleMargin]: string | null;
} = {
  none: null,
  xs: 'marginXSmall',
  ...
  xxl: 'marginXXLarge',
};

const classes = classNames(
  'euiHorizontalRule',
  {
    [`euiHorizontalRule--${marginToClassNameMap[margin]}`]: margin && margin !== 'none',
  },
);

2c. Removing vs. keeping classNames

In the above scenarios, removing the -- modifier classNames/maps may be a perfectly valid choice as well to clean up our classNames logic. Be sure to search through Kibana first for the modifier(s) classes:

1. If no frequent Kibana usages come up (e.g. in CSS overrides or test selectors) outside of snapshots, fantastic! Go ahead and remove the classes.
2. If there are minor usages, consider replacing the modifier class with a [data] attribute instead that consumers can target instead of a class.

NOTE: Generally, do not remove the top level className (e.g. .euiComponent) or child element classNames (e.g. .euiComponent__child). These classes serve as useful hooks/markers for consumers to use (both for CSS overrides and test selectors).

3. Move and remove style Amsterdam overrides (if present)

Check src/themes/amsterdam/overrides for component style overrides. If overrides are present:

• Find the Sass module containing the override styles in src/themes/amsterdam/overrides/. The file will be named _{component}.scss.
• Prioritize/move these styles into the new {component}.styles.ts file
• Delete the old Sass file
• In src/themes/amsterdam/overrides/_index.scss, remove the component Sass module import

4. Update component tests

• Once styling changes have been tested and verified in browser, update component snapshots
• Update the component test file ({component}.test.tsx) to use the shouldRenderCustomStyles utility:

Example

import { shouldRenderCustomStyles } from '../../test/internal';

describe('EuiAvatar', () => {
  test('it renders', () => { ... });

  shouldRenderCustomStyles(<EuiAvatar name="name" />);

  // more tests
}

5. Remove styling variables used by the EUI documentation site (if present)

• Remove any styling variables related to the component from the rendered .json files by running the command yarn compile-scss

6. Deprecate any component-specific mixins

• Add an @warn message within the global_styling/mixins/{component name}.scss file providing a recommendation if possible

Example if the recommendation is to use the actual React component

@mixin componentMixin(){
  ...
  @warn 'componentMixin() has been deprecated. Wrap your usage with <EuiComponentName /> instead.';
}

7. Update the documentation site playground (if using withEuiTheme HOC)

• Import and use the component class that is wrapped by withEuiTheme()
• Pass true as the second argument to propUtilityForPlayground

-  const docgenInfo = Array.isArray(EuiAccordion.__docgenInfo)
-    ? EuiAccordion.__docgenInfo[0]
-    : EuiAccordion.__docgenInfo;
-  const propsToUse = propUtilityForPlayground(docgenInfo.props);
+  const docgenInfo = Array.isArray(EuiAccordionClass.__docgenInfo)
+    ? EuiAccordionClass.__docgenInfo[0]
+    : EuiAccordionClass.__docgenInfo;
+  const propsToUse = propUtilityForPlayground(docgenInfo.props, true);

8. Changelog

Be sure to add the following header:

**CSS-in-JS conversions**

- Converted ___ to Emotion

If any Sass variables or mixins were removed, append them to the line item use a semi-colon separator

- Converted __ to Emotion; Removed `$___`

[cchaos]

EDIT: We've moved this conversion checklist to our GitHub PR template instead. See #6294