[Docs] Add ThemeLanguages and new Breakpoints page

src-docs/src/components/guide_page/guide_page.js

@@ -6,8 +6,11 @@ import {
   EuiPageHeader,
   EuiPageContent,
   EuiPageContentBody,
+  EuiSpacer,
 } from '../../../../src/components';
 
+import { LanguageSelector } from '../with_theme';
+
 const GuidePageComponent = ({
   children,
   title,
@@ -18,6 +21,11 @@ const GuidePageComponent = ({
   location,
   match,
   history,
+  description,
+  rightSideItems: _rightSideItems,
+  tabs: _tabs,
+  notice,
+  showThemeLanguageToggle,
 }) => {
   const betaBadge = isBeta ? (
     <EuiBetaBadge
@@ -78,16 +86,37 @@ const GuidePageComponent = ({
     });
   };
 
+  const renderNotice = () => {
+    if (notice) {
+      return (
+        <>
+          <EuiPageContentBody role="region" aria-label="Notice" restrictWidth>
+            {notice}
+          </EuiPageContentBody>
+          <EuiSpacer size="l" />
+        </>
+      );
+    }
+  };
+
+  const rightSideItems = _rightSideItems || [];
+  if (showThemeLanguageToggle) {
+    rightSideItems.push(<LanguageSelector />);
+  }
+
   return (
     <>
+      {renderNotice()}
       <EuiPageHeader
         restrictWidth
         pageTitle={
           <>
             {title} {betaBadge}
           </>
         }
-        tabs={renderTabs()}
+        tabs={renderTabs() || _tabs}
+        description={description}
+        rightSideItems={rightSideItems}
       >
         {intro}
       </EuiPageHeader>
@@ -127,6 +156,11 @@ GuidePageComponent.propTypes = {
   location: PropTypes.object,
   match: PropTypes.object,
   history: PropTypes.object,
+  description: PropTypes.node,
+  notice: PropTypes.node,
+  tabs: PropTypes.arrayOf(PropTypes.object),
+  rightSideItems: PropTypes.arrayOf(PropTypes.node),
+  showThemeLanguageToggle: PropTypes.bool,
 };
 
 export const GuidePage = withRouter(GuidePageComponent);

src-docs/src/components/guide_page/guide_page_header.tsx

@@ -143,6 +143,8 @@ export const GuidePageHeader: React.FunctionComponent<GuidePageHeaderProps> = ({
 
   return (
     <EuiHeader
+      role="region"
+      aria-label="EUI Docs app bar"
       position="fixed"
       theme="dark"
       sections={[

src-docs/src/components/index.js

@@ -13,4 +13,4 @@ export { GuideSectionContainer as GuideSection } from './guide_section/guide_sec
 
 export { GuideSectionTypes } from './guide_section/guide_section_types';
 
-export { ThemeProvider, ThemeContext } from './with_theme';
+export { ThemeProvider, ThemeContext, LanguageSelector } from './with_theme';

src-docs/src/components/with_theme/index.ts

@@ -1 +1,2 @@
 export { ThemeProvider, ThemeContext } from './theme_context';
+export { LanguageSelector } from './language_selector';

src-docs/src/components/with_theme/language_selector.tsx

@@ -0,0 +1,71 @@
+import React, { useContext, useState } from 'react';
+
+import {
+  EuiButtonGroup,
+  EuiIcon,
+  EuiLink,
+  EuiText,
+  EuiTourStep,
+} from '../../../../src/components';
+
+import {
+  ThemeContext,
+  theme_languages,
+  THEME_LANGUAGES,
+} from './theme_context';
+
+const NOTIF_STORAGE_KEY = 'js_vs_sass_notification';
+
+export const LanguageSelector = ({
+  onChange,
+}: {
+  onChange?: (id: string) => void;
+}) => {
+  const themeContext = useContext(ThemeContext);
+  const toggleIdSelected = themeContext.themeLanguage;
+  const onLanguageChange = (optionId: string) => {
+    themeContext.changeThemeLanguage(optionId as THEME_LANGUAGES['id']);
+    onChange?.(optionId);
+    setTourIsOpen(false);
+    localStorage.setItem(NOTIF_STORAGE_KEY, 'dismissed');
+  };
+
+  const [isTourOpen, setTourIsOpen] = useState(
+    localStorage.getItem(NOTIF_STORAGE_KEY) !== 'dismissed'
+  );
+
+  const onTourDismiss = () => {
+    setTourIsOpen(false);
+    localStorage.setItem(NOTIF_STORAGE_KEY, 'dismissed');
+  };
+
+  return (
+    // @ts-ignore Fixes for tour in another PR
+    <EuiTourStep
+      content={
+        <EuiText style={{ maxWidth: 320 }}>
+          <p>Select your preferred styling language with this toggle button.</p>
+        </EuiText>
+      }
+      isStepOpen={isTourOpen}
+      onFinish={onTourDismiss}
+      step={1}
+      stepsTotal={1}
+      title={
+        <>
+          <EuiIcon type="bell" size="s" /> &nbsp; Theming update
+        </>
+      }
+      footerAction={<EuiLink onClick={onTourDismiss}>Got it!</EuiLink>}
+    >
+      <EuiButtonGroup
+        buttonSize="m"
+        color="accent"
+        legend="Language selector"
+        options={theme_languages}
+        idSelected={toggleIdSelected}
+        onChange={(id) => onLanguageChange(id)}
+      />
+    </EuiTourStep>
+  );
+};

src-docs/src/components/with_theme/theme_context.tsx

@@ -6,17 +6,43 @@ import { EuiThemeProvider } from '../../../../src/services';
 import { EuiThemeAmsterdam } from '../../../../src/themes/eui-amsterdam/theme';
 import { EuiThemeDefault } from '../../../../src/themes/eui/theme';
 
+export const STYLE_STORAGE_KEY = 'js_vs_sass_preference';
+
+export type THEME_LANGUAGES = {
+  id: 'language--js' | 'language--sass';
+  label: string;
+  title: string;
+};
+
+export const theme_languages: THEME_LANGUAGES[] = [
+  {
+    id: 'language--js',
+    label: 'JS',
+    title: 'Language selector: CSS-in-JS',
+  },
+  {
+    id: 'language--sass',
+    label: 'Sass',
+    title: 'Language selector: Sass',
+  },
+];
+
 const THEME_NAMES = EUI_THEMES.map(({ value }) => value);
+const THEME_LANGS = theme_languages.map(({ id }) => id);
 
 const defaultState = {
-  theme: THEME_NAMES[2],
+  themeLanguage: THEME_LANGS[0],
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  changeThemeLanguage: (language: THEME_LANGUAGES['id']) => {},
+  theme: THEME_NAMES[0],
   changeTheme: (themeValue: EUI_THEME['value']) => {
     applyTheme(themeValue);
   },
 };
 
 interface State {
   theme: EUI_THEME['value'];
+  themeLanguage: THEME_LANGUAGES['id'];
 }
 
 export const ThemeContext = React.createContext(defaultState);
@@ -25,12 +51,19 @@ export class ThemeProvider extends React.Component<object, State> {
   constructor(props: object) {
     super(props);
 
+    let themeLanguage = localStorage.getItem(
+      STYLE_STORAGE_KEY
+    ) as THEME_LANGUAGES['id'];
+    if (!themeLanguage || !THEME_LANGS.includes(themeLanguage))
+      themeLanguage = defaultState.themeLanguage;
+
     let theme = localStorage.getItem('theme');
     if (!theme || !THEME_NAMES.includes(theme)) theme = defaultState.theme;
     applyTheme(theme);
 
     this.state = {
       theme,
+      themeLanguage,
     };
   }
 
@@ -41,14 +74,22 @@ export class ThemeProvider extends React.Component<object, State> {
     });
   };
 
+  changeThemeLanguage = (language: THEME_LANGUAGES['id']) => {
+    this.setState({ themeLanguage: language }, () => {
+      localStorage.setItem(STYLE_STORAGE_KEY, language);
+    });
+  };
+
   render() {
     const { children } = this.props;
-    const { theme } = this.state;
+    const { theme, themeLanguage } = this.state;
     return (
       <ThemeContext.Provider
         value={{
           theme,
+          themeLanguage,
           changeTheme: this.changeTheme,
+          changeThemeLanguage: this.changeThemeLanguage,
         }}
       >
         <EuiThemeProvider

src-docs/src/routes.js

@@ -224,6 +224,7 @@ import { SuperSelectExample } from './views/super_select/super_select_example';
 
 import { ThemeExample } from './views/theme/theme_example';
 import ThemeValues from './views/theme/values';
+import Breakpoints from './views/theme/breakpoints/breakpoints';
 
 /** Elastic Charts */
 
@@ -248,18 +249,20 @@ const createExample = (example, customTitle) => {
 
   const {
     title,
-    intro,
     sections,
     beta,
     isNew,
     playground,
     guidelines,
+    ...rest
   } = example;
-  sections.forEach((section) => {
+  const filteredSections = sections.filter((section) => section !== undefined);
+
+  filteredSections.forEach((section) => {
     section.id = section.title ? slugify(section.title) : undefined;
   });
 
-  const renderedSections = sections.map((section, index) =>
+  const renderedSections = filteredSections.map((section, index) =>
     createElement(GuideSection, {
       // Using index as the key because not all require a `title`
       key: index,
@@ -280,10 +283,10 @@ const createExample = (example, customTitle) => {
     <EuiErrorBoundary>
       <GuidePage
         title={title}
-        intro={intro}
         isBeta={beta}
         playground={playgroundComponent}
         guidelines={guidelines}
+        {...rest}
       >
         {renderedSections}
       </GuidePage>
@@ -293,7 +296,7 @@ const createExample = (example, customTitle) => {
   return {
     name: customTitle || title,
     component,
-    sections,
+    sections: filteredSections,
     isNew,
     hasGuidelines: typeof guidelines !== 'undefined',
   };
@@ -331,10 +334,25 @@ const navigation = [
         name: 'Colors',
         component: ColorGuidelines,
       },
-      createExample(SassGuidelines, 'Sass'),
       createExample(WritingGuidelines, 'Writing'),
     ],
   },
+  {
+    name: 'Theming',
+    items: [
+      createExample(ThemeExample, 'Theme provider'),
+      {
+        name: 'Global values',
+        component: ThemeValues,
+        isNew: true,
+      },
+      {
+        name: 'Breakpoints',
+        component: Breakpoints,
+      },
+      createExample(SassGuidelines, 'Sass'),
+    ],
+  },
   {
     name: 'Layout',
     items: [
@@ -482,17 +500,6 @@ const navigation = [
       WindowEventExample,
     ].map((example) => createExample(example)),
   },
-  {
-    name: 'Theming',
-    items: [
-      createExample(ThemeExample, 'Theme provider'),
-      {
-        name: 'Global values',
-        component: ThemeValues,
-        isNew: true,
-      },
-    ],
-  },
   {
     name: 'Package',
     items: [Changelog, I18nTokens],

src-docs/src/views/guidelines/_index.scss

@@ -331,6 +331,16 @@
 
 @import 'colors/color_section';
 
+@each $key, $size in $euiBreakpoints {
+  .guideSass__breakpoint--#{$key} {
+    display: none;
+
+    @include euiBreakpoint($key) {
+      display: block;
+    }
+  }
+}
+
 @include euiBreakpoint('xl') {
   .guideSass__breakpointExample {
     background: $euiColorPrimary;

src-docs/src/views/guidelines/sass.js

@@ -4,7 +4,6 @@ import { Link } from 'react-router-dom';
 import { ThemeContext } from '../../components';
 import { Typography } from './sass/typography';
 import { Animation } from './sass/animation';
-import { Breakpoints } from './sass/breakpoints';
 import { Shadow } from './sass/shadow';
 import { Border } from './sass/border';
 import { Color } from './sass/color';
@@ -203,11 +202,6 @@ export const SassGuidelines = {
       wrapText: false,
       text: <Shadow />,
     },
-    {
-      title: 'Media queries and breakpoints',
-      wrapText: false,
-      text: <Breakpoints />,
-    },
     {
       title: 'Animation',
       wrapText: false,