From e6ccac87490d625be94e5af9452c1eca2898415e Mon Sep 17 00:00:00 2001 From: Cee Chen <549407+cee-chen@users.noreply.github.com> Date: Fri, 20 Sep 2024 14:06:27 -0700 Subject: [PATCH] [Docs] Update references to Sass/Emotion migration (#8029) --- README.md | 7 +- packages/eui/README.md | 70 +---- .../src/components/codesandbox/link.js | 37 +-- .../guide_tabbed_page/guide_tabbed_page.tsx | 21 +- .../guidelines/getting_started/_app_setup.tsx | 71 ++--- .../getting_started/_customizing.tsx | 105 -------- .../guidelines/getting_started/_tokens.tsx | 101 ------- .../getting_started/getting_started.js | 167 +++++++----- .../views/theme/_components/_theme_notice.tsx | 53 ++-- .../src/views/theme/borders/borders.tsx | 1 - .../src-docs/src/views/theme/consuming.tsx | 4 +- .../src/views/theme/customizing/_sass.tsx | 25 +- .../src/views/theme/customizing/values.tsx | 1 - .../src-docs/src/views/theme/other/other.tsx | 1 - .../docs/01_guidelines/getting_started.mdx | 249 +++++++----------- wiki/consuming-eui/README.md | 26 +- 16 files changed, 298 insertions(+), 641 deletions(-) delete mode 100644 packages/eui/src-docs/src/views/guidelines/getting_started/_customizing.tsx delete mode 100644 packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx diff --git a/README.md b/README.md index 694c966f993..54db578deb3 100644 --- a/README.md +++ b/README.md @@ -45,12 +45,9 @@ This activity counter can be soft reset by commenting on the issue directly, but The EUI team, like everyone else, has a finite amount of time and resources, and it is not humanly possible for us to implement every task or feature requested of us. However, that's where the beauty of open source comes in - if your request is important to you, we strongly encourage you to [contribute code directly to EUI](wiki/contributing-to-eui/) that addresses your issue or request! - -### What is the status of EUI's theming? +### I have more questions! -The EUI library was previously built upon Sass and is in the process of migrating to CSS-in-JS (specifically [Emotion](https://emotion.sh)). While this work is in progress, we ask for your patience with our in-between state in areas such as documentation and setup. - -If you're a Kibana developer with questions around CSS-in-JS usage in Kibana, please check out our [FAQ discussion](https://github.com/elastic/eui/discussions/6828)! +The EUI team has ongoing FAQs for more transient or component-specific questions. [Please see the FAQ section in our GitHub discussions here](https://github.com/elastic/eui/discussions/categories/faq). ## Wiki diff --git a/packages/eui/README.md b/packages/eui/README.md index 694c966f993..7012e6ff7d0 100644 --- a/packages/eui/README.md +++ b/packages/eui/README.md @@ -1,69 +1 @@ - - -# Elastic UI Framework - -**The Elastic UI Framework is a collection of React UI components for quickly building user interfaces at Elastic.** - -Check out our [full documentation site][docs] which contains many examples of components in the EUI framework aesthetic, and how to use them in your products. Our FAQ below covers common usage questions — for other general questions regarding EUI, check out the [Discussions tab](https://github.com/elastic/eui/discussions). - -> [!NOTE] -> We're in the process of migrating this repository to a monorepo structure. You can find `@elastic/eui` files in the [packages/eui](https://github.com/elastic/eui/tree/main/packages/eui) directory. - -## Frequently Asked Questions - -### What is the Elastic UI Framework? - -The Elastic UI Framework (EUI) is a design library in use at Elastic to build React applications that need to share our branding and aesthetics. It distributes typed UI React components and static assets for use in building web layouts. Alongside the React components, we ship theme & style utilities that can be used independently on their own. - -The primary goal of this library is to provide reusable UI components that can be used throughout Elastic's web products. As React components, they remove CSS from the process of building UIs. As a single source of truth, the framework allows our designers to make changes to our aesthetic directly in the code. And unit test coverage for the UI components allows us to deliver a stable "API for user interfaces". - -### Can I use EUI? - -Please see Elastic's licensing FAQ: [I’m using EUI or Elastic Charts in my application outside of Kibana, how does this affect me?][licensing-faq] - -### Why is EUI open source? - -Many of Elastic's products are open source and rely upon this library to function. The Elastic UI Framework began as a folder of code in Kibana and we decided it could be used beyond that codebase. It exists as an independent library so that patterns can be shared across teams and design standards can be scaled across our organization. Since most of our products are open source, we treat this one similarly as far as public publishing and conversation even if its usage tends to focus more inward towards Elastic itself. - -### What is the versioning, release, and upgrade strategy? - -We use [semver](https://semver.org/) for versioning and use that to denote breaking changes in EUI upgrades. Traditionally we consider API changes in our prop names or existing component functionality to be a reason for a breaking change, but do not track the renaming of CSS selectors, mixins or other style changes under this same rigor. - -Traditionally releases are made weekly against whatever is in the `main` branch and you can upgrade from NPM as you see fit. - -### Can I contribute to EUI? - -Yes! We welcome community-contributed PRs, especially around feature requests that the EUI team may not have bandwidth to carry out alone. You can find documentation around creating and submitting new components in [our wiki](wiki/contributing-to-eui/). - -### What about reporting bugs and feature requests? - -Bug reports and feature requests are most welcome, but our roadmap and prioritization are driven primarily by [internal Elastic usage](wiki/contributing-to-eui#how-we-assign-work-and-define-our-roadmap). - -Please note that in order to keep our backlog manageable and focused on tasks we intend to complete, feature requests & tech debt issues that are inactive for a year will be auto-closed (bugs will remain open if determined to be reproducible and valid). - -This activity counter can be soft reset by commenting on the issue directly, but please do so mindfully. We would ask that you proactively let the EUI team know why this request matters to you or how it impacts you or your users, in order to help us prioritize accordingly. - -The EUI team, like everyone else, has a finite amount of time and resources, and it is not humanly possible for us to implement every task or feature requested of us. However, that's where the beauty of open source comes in - if your request is important to you, we strongly encourage you to [contribute code directly to EUI](wiki/contributing-to-eui/) that addresses your issue or request! - - -### What is the status of EUI's theming? - -The EUI library was previously built upon Sass and is in the process of migrating to CSS-in-JS (specifically [Emotion](https://emotion.sh)). While this work is in progress, we ask for your patience with our in-between state in areas such as documentation and setup. - -If you're a Kibana developer with questions around CSS-in-JS usage in Kibana, please check out our [FAQ discussion](https://github.com/elastic/eui/discussions/6828)! - -## Wiki - -Our wiki docs contain instructions and guidelines on multiple areas of EUI usage and development that are too detailed for an initial README. For more information, see: - -- [Consuming EUI](wiki/consuming-eui) -- [Contributing to EUI](wiki/contributing-to-eui/) -- [Running EUI locally](wiki/contributing-to-eui/running-eui-locally.md) - -## License - -[Dual-licensed under Elastic v2 and Server Side Public License, v1][license]. See Elastic's [licensing FAQ][licensing-faq] for details. - -[license]: LICENSE.txt -[licensing-faq]: https://www.elastic.co/pricing/faq/licensing#im-using-eui-or-elastic-charts-in-my-application-outside-of-kibana-how-does-this-affect-me -[docs]: https://elastic.github.io/eui/ +## See [the top-level repo README](../../#readme) and [wiki](../../wiki) for more information on consuming and contributing to EUI. diff --git a/packages/eui/src-docs/src/components/codesandbox/link.js b/packages/eui/src-docs/src/components/codesandbox/link.js index 214a8aae8de..4ed303ea954 100644 --- a/packages/eui/src-docs/src/components/codesandbox/link.js +++ b/packages/eui/src-docs/src/components/codesandbox/link.js @@ -1,13 +1,12 @@ import React from 'react'; import { getParameters } from 'codesandbox/lib/api/define'; +import { useEuiTheme } from '../../../../src/services'; import { cleanEuiImports, hasDisplayToggles, listExtraDeps, } from '../../services'; -import { ThemeContext } from '../with_theme'; - const pkg = require('../../../../package.json'); const getVersion = (packageName) => { @@ -33,39 +32,14 @@ const getVersion = (packageName) => { const displayTogglesRawCode = require('!!raw-loader!../../views/form_controls/display_toggles').default; -export const CodeSandboxLink = ({ ...rest }) => { - return ( - - {(context) => } - - ); -}; - /* 1 */ -export const CodeSandboxLinkComponent = ({ +export const CodeSandboxLink = ({ children, className, content, type = 'js', - context, }) => { - const isDarkMode = context.theme.includes('dark'); - const colorMode = isDarkMode ? 'dark' : 'light'; - - const cssFile = `@elastic/eui/dist/eui_theme_${colorMode}.css`; - - const providerPropsObject = {}; - // Only add configuration if it isn't the default - if (isDarkMode) { - providerPropsObject.colorMode = 'dark'; - } - // Can't spread an object inside of a string literal - const providerProps = Object.keys(providerPropsObject) - .map((prop) => { - const value = providerPropsObject[prop]; - return value !== null ? `${prop}="${value}"` : `${prop}={${value}}`; - }) - .join(' '); + const { colorMode } = useEuiTheme(); let demoContent; @@ -165,8 +139,7 @@ import '@elastic/charts/dist/theme_only_${colorMode}.css';` content: demoContent, }, 'index.js': { - content: `import '${cssFile}'; -import React from 'react'; + content: `import React from 'react'; import { createRoot } from 'react-dom/client'; import createCache from '@emotion/cache'; import { EuiProvider, euiStylisPrefixer } from '@elastic/eui'; @@ -182,7 +155,7 @@ cache.compat = true; const root = createRoot(document.getElementById('root')); root.render( - + );`, diff --git a/packages/eui/src-docs/src/components/guide_tabbed_page/guide_tabbed_page.tsx b/packages/eui/src-docs/src/components/guide_tabbed_page/guide_tabbed_page.tsx index 576de96f5dd..78116df1354 100644 --- a/packages/eui/src-docs/src/components/guide_tabbed_page/guide_tabbed_page.tsx +++ b/packages/eui/src-docs/src/components/guide_tabbed_page/guide_tabbed_page.tsx @@ -62,16 +62,15 @@ export const GuideTabbedPage: FunctionComponent = ({ const currentLanguage = themeContext.themeLanguage; const showSass = currentLanguage.includes('sass'); - const headerBadge = - isBeta || (showThemeLanguageToggle && !showSass) ? ( - - ) : isNew ? ( - - ) : undefined; + const headerBadge = isBeta ? ( + + ) : isNew ? ( + + ) : undefined; let tabs: | Array<{ @@ -190,7 +189,7 @@ export const GuideTabbedPage: FunctionComponent = ({ }; const renderNotice = () => { - if (!showSass && notice) { + if (showSass && notice) { return (
diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx b/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx index cce01cad10e..9ad5022204e 100644 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx +++ b/packages/eui/src-docs/src/views/guidelines/getting_started/_app_setup.tsx @@ -1,71 +1,52 @@ -import React, { FunctionComponent } from 'react'; +import React from 'react'; import { Link } from 'react-router-dom'; import { EuiCodeBlock, - useEuiTheme, EuiCode, EuiSpacer, EuiText, - EuiCallOut, + EuiLink, } from '../../../../../src'; -type AppSetup = {}; - -export const AppSetup: FunctionComponent = ({}) => { - const { colorMode } = useEuiTheme(); +export const AppSetup = () => { + return ( + <> + +

+ EUI uses CSS-in-JS (specifically{' '} + + Emotion + + ) for its styles and theming. As such, we require an{' '} + {''} wrapper around your application + in order for various theme-related UI & UX (such as dark/light mode + switching) to work as expected. +

+ - const appSetup = ( - - {`import React from 'react'; -import '@elastic/eui/dist/eui_theme_${colorMode.toLowerCase()}.css'; + + + {`import React from 'react'; import { EuiProvider, EuiText } from '@elastic/eui'; const MyApp = () => ( - +

Hello World!

 ); export default MyApp;`} - - ); - - return ( - <> - -

- While EUI is in the process of converting from a Sass based theme to - CSS-in-JS via Emotion. We require that both the{' '} - - EuiProvider - {' '} - and the compiled CSS (or raw Sass) files be imported - during this transition. -

- - - - - -

- EUI provides a general context provider to handle global aspects like - light and dark theme. You can import these default themes through - their respective compiled CSS files. Use the{' '} - .min.css file extension for the minified version. -

- - - - {appSetup} +

- For the dark theme, you can swap the words light{' '} - for dark.
For more configuration options of the provider, see the{' '} - EuiProvider documentation. + + EuiProvider documentation + + .

diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/_customizing.tsx b/packages/eui/src-docs/src/views/guidelines/getting_started/_customizing.tsx deleted file mode 100644 index bd19330490e..00000000000 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/_customizing.tsx +++ /dev/null @@ -1,105 +0,0 @@ -import React, { FunctionComponent, useContext } from 'react'; -import { Link } from 'react-router-dom'; - -import { - EuiCodeBlock, - EuiSplitPanel, - EuiFlexGroup, - EuiFlexItem, - EuiText, - EuiHorizontalRule, - EuiCode, -} from '../../../../../src'; - -import { GuideSectionExampleCode } from '../../../components/guide_section/guide_section_parts/guide_section_code'; -import { LanguageSelector, ThemeContext } from '../../../components/with_theme'; -const overrideSimpleSource = require('!!raw-loader!../../theme/override_simple'); - -export const CustomizeTokens = () => { - const themeContext = useContext(ThemeContext); - let files; - switch (themeContext.theme) { - case 'dark': - files = "@import '@elastic/eui/src/themes/amsterdam/theme_dark';"; - break; - default: - files = "@import '@elastic/eui/src/themes/amsterdam/theme_light';"; - break; - } - - return ( - - {`// mytheme.scss -$euiColorPrimary: #7B61FF; - -// The following rebuilds the entire EUI component styles -${files} - -@import 'your/custom/styles';`} - - ); -}; - -export const Customizing: FunctionComponent = () => { - const themeContext = useContext(ThemeContext); - const currentLanguage = themeContext.themeLanguage; - const showSass = currentLanguage.includes('sass'); - - return ( - - - - - -

- - Keep an eye out for this language selector that will allow you - to view the syntax for either the Sass or CSS-in-JS (Emotion) - theming mechanisms. - -

- - - - - - - - - {showSass ? ( - <> - - -

- This will require style, css, postcss, and sass loaders and a - full re-compile of all EUI component styles. -

- - - - - - - ) : ( - <> - - -

- You can pass along a full or partial list of global{' '} - overrides to the{' '} - - EuiProvider - {' '} - which will update the EUI components that are currently using - the Emotion method of theming. -

- - - - - - - )} - - ); -}; diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx b/packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx deleted file mode 100644 index 1731c112295..00000000000 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/_tokens.tsx +++ /dev/null @@ -1,101 +0,0 @@ -import React, { FunctionComponent, useContext } from 'react'; -import { Link } from 'react-router-dom'; - -import { - EuiCodeBlock, - EuiSplitPanel, - EuiFlexGroup, - EuiFlexItem, - EuiText, - EuiHorizontalRule, - EuiCode, -} from '../../../../../src'; - -import { GuideSectionExampleCode } from '../../../components/guide_section/guide_section_parts/guide_section_code'; -import { LanguageSelector, ThemeContext } from '../../../components/with_theme'; -const consumingSource = require('!!raw-loader!../../theme/consuming'); - -const ImportOutsideExample = () => { - const themeContext = useContext(ThemeContext); - let files; - switch (themeContext.theme) { - case 'dark': - files = `@import '@elastic/eui/src/themes/amsterdam/colors_dark'; -@import '@elastic/eui/src/themes/amsterdam/globals';`; - break; - default: - files = `@import '@elastic/eui/src/themes/amsterdam/colors_light'; -@import '@elastic/eui/src/themes/amsterdam/globals';`; - break; - } - - return ( - - {`// index.scss -${files} - -@import 'your/custom/styles';`} - - ); -}; - -export const Tokens: FunctionComponent = () => { - const themeContext = useContext(ThemeContext); - const currentLanguage = themeContext.themeLanguage; - const showSass = currentLanguage.includes('sass'); - - return ( - - - - - -

- - Keep an eye out for this language selector that will allow you - to view the syntax for either the Sass or CSS-in-JS (Emotion) - theming mechanisms. - -

- - - - - - - - - {showSass ? ( - <> - - -

This will require style, css, postcss, and sass loaders.

- - - - - - - ) : ( - <> - - -

- As long as you have wrapped your application with{' '} - - EuiProvider - - , you have access to the JS theme tokens via{' '} - useEuiTheme() and Emotion's{' '} - css prop. -

- - - - - - - )} - - ); -}; diff --git a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js index 88c48d5e53f..f30b0bb294a 100644 --- a/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js +++ b/packages/eui/src-docs/src/views/guidelines/getting_started/getting_started.js @@ -1,12 +1,20 @@ import React from 'react'; import { Link } from 'react-router-dom'; -import { EuiCodeBlock, EuiCode, EuiText, EuiSpacer } from '../../../../../src'; +import { + EuiCodeBlock, + EuiCode, + EuiText, + EuiSpacer, + EuiPanel, + EuiCallOut, + EuiLink, +} from '../../../../../src'; import { AppSetup } from './_app_setup'; -import { Tokens } from './_tokens'; -import { Customizing } from './_customizing'; -import { ThemeNotice } from '../../../views/theme/_components/_theme_notice.tsx'; +import { GuideSectionExampleCode } from '../../../components/guide_section/guide_section_parts/guide_section_code'; +const consumingSource = require('!!raw-loader!../../theme/consuming'); +const overrideSimpleSource = require('!!raw-loader!../../theme/override_simple'); import { euiProviderComponentDefaultsSnippet } from '../../provider/provider_component_defaults'; export const GettingStarted = { @@ -72,58 +80,117 @@ export const GettingStarted = { <>

- To build your custom components using EUI theme variables, - functions, and mixins, you will need to consume them through one - of the Sass,{' '} - Emotion, or{' '} - - JSON import - {' '} - methods. + You can build custom components using EUI's theme tokens, consumed + via useEuiTheme(). The below example uses + Emotion's css prop, but any CSS-in-JS library + should be able to interpolate the JS variables. +

+

+ For more ways to consume EUI's theme, see the{' '} + + EuiThemeProvider documentation + + .

- + + + -

Customizing the style tokens

+

Customizing with classes

- EUI can be slightly customized to fit your branding needs by - altering the base tokens like color and typography. Simply declare - your token overrides before importing the whole EUI theme. This - will re-compile all of the EUI components with your colors. + For consumers using vanilla or preprocessed CSS, all components + allow you to pass a custom className prop, + which will be appended onto the component.

+ + Avoid overwriting .eui class names + + } + > + EUI's class names are not a guaranteed API and are prone to + change, which will risk breaking your theme. Target your custom + classNames instead. + +

- For a full list of global tokens visit{' '} - Customizing theme. + While EUI's styles are generally low in{' '} + + specificity + {' '} + due to our usage of CSS-in-JS, you may need to ensure that your + CSS is defined after ours in your {''}.{' '} + See{' '} + + EuiProvider's cache customization + {' '} + for more style injection options.

- - - + + ( + <> + + Hello world! + +);`, + }} + /> + + -

Do not use in conjunction with the compiled CSS.

-

If you provide both, it will duplicate the imported styles.

-

Touch the least amount of variables possible.

+

Customizing the style tokens

- By nature EUI is very rigid. You shouldn't need much to make + EUI can be slightly customized to fit your branding needs by + altering the base tokens like color and typography. You can pass a + full or partial list of override tokens to the{' '} + EuiProvider's modify prop. +

+ + By nature, EUI is very rigid. You shouldn't need much to make drastic changes to color. Most themes are less then a dozen variable overwrites in total. -

-

- Do not overwrite individual component variables or{' '} - .eui class names. -

+ +

- Although this may be possible, components are much more prone to - change and you'll risk breaking your theme. All EUI - components accept custom a className which you - can use to append your custom styles. + For a full list of global tokens, visit{' '} + Customizing themes. + For more examples of the modify prop, see the{' '} + + EuiThemeProvider docs + + .

+ + + + ), }, @@ -241,34 +308,6 @@ import { findByTestSubject, render, screen } from '@elastic/eui/lib/test/rtl'; / ), }, - { - title: 'Customizing with classes', - wrapText: false, - text: ( - <> - -

- We do not recommend customizing EUI components by applying styles - directly to EUI classes, eg. .euiButton. All - components allow you to pass a custom className{' '} - prop directly to the component which will then append this to the - class list. Utilizing the cascade feature of CSS, you can then - customize by overriding styles so long as your styles are imported{' '} - after the EUI import. -

- - - - {''} - - -

Renders as:

- - {'