[Page Layouts] Adding content props to EuiPageHeader for pre-determined page layout patterns

CHANGELOG.md

@@ -1,12 +1,19 @@
 ## [`master`](https://github.com/elastic/eui/tree/master)
 
 - Added `isLoading` prop and added `EuiOverlayMask` directly to `EuiConfirmModal` ([#4421](https://github.com/elastic/eui/pull/4421))
+- Added content-specific props (`pageTitle`, `description`, `tabs`, `rightSideContent`) to `EuiPageHeader` by creating a new `EuiPageHeaderContent` component ([#4451](https://github.com/elastic/eui/pull/4451))
+- Added `isActive` parameter to the `useIsWithinBreakpoints` hook ([#4451](https://github.com/elastic/eui/pull/4451))
 
 **Bug fixes**
 
 - Fixed `id` usage throughout `EuiTreeView` to respect custom ids and stop conflicts in generated ids ([#4435](https://github.com/elastic/eui/pull/4435))
 - Fixed `EuiTabs` `role` if no tabs are passed in ([#4435](https://github.com/elastic/eui/pull/4435))
 
+**Theme: Amsterdam**
+
+- Increased `EuiPage`'s default `restrictWidth` size to `1200px` (extra large breakpoint) ([#4451](https://github.com/elastic/eui/pull/4451))
+- Reduced size of `euiBottomShadowSmall` by one layer ([#4451](https://github.com/elastic/eui/pull/4451))
+
 ## [`31.4.0`](https://github.com/elastic/eui/tree/v31.4.0)
 
 - Added `getDefaultEuiMarkdownProcessingPlugins` method for better control over `EuiMarkdownEditor`'s toolbar UI ([#4383](https://github.com/elastic/eui/pull/4383))

src-docs/src/components/guide_components.scss

@@ -96,7 +96,7 @@ $guideZLevelHighest: $euiZLevel9 + 1000;
   min-height: 100vh;
   background-color: $euiColorEmptyShade;
   border-left: $euiBorderThin;
-  max-width: 1000px;
+  max-width: $euiPageDefaultMaxWidth;
   margin-left: 240px;
 }
 
@@ -105,11 +105,16 @@ $guideZLevelHighest: $euiZLevel9 + 1000;
     min-height: 460px;
   }
 
-  div {
+  > div,
+  > div > div {
     background: transparentize($euiColorPrimary, .9);
   }
 }
 
+.guideDemo__highlightLayout--single {
+  background: transparentize($euiColorPrimary, .9);
+}
+
 .guideDemo__highlightSpacer {
   .euiSpacer {
     background: transparentize($euiColorPrimary, .9);

src-docs/src/services/playground/_playground_compiler.scss

@@ -11,4 +11,4 @@
   @if (lightness($euiTextColor) < 50) {
     background: $euiColorDarkestShade;
   }
-}
+}

src-docs/src/services/playground/createOptionalEnum.js

@@ -2,7 +2,7 @@ export const createOptionalEnum = (prop = { options: {} }) => {
   const newProp = {
     ...prop,
     options: {
-      none: '-- No value selected --',
+      none: '',
       ...prop.options,
     },
     defaultValue: 'none',

src-docs/src/services/playground/iconValidator.js

@@ -1,8 +1,9 @@
 import { iconTypes } from '../../views/icon/icons';
+import { iconTypes as logoTypes } from '../../views/icon/logos';
 import { mapOptions } from './mapOptions';
 import { PropTypes } from 'react-view';
 
-const iconOptions = mapOptions(iconTypes);
+const iconOptions = mapOptions(iconTypes.concat(logoTypes));
 
 export const iconValidator = (prop = { custom: {} }) => {
   const newProp = {

src-docs/src/services/playground/index.js

@@ -6,3 +6,4 @@ export { iconValidator } from './iconValidator';
 export { createOptionalEnum } from './createOptionalEnum';
 export { dummyFunction } from './dummyFunction';
 export { simulateFunction } from './simulateFunction';
+export { generateAst, generateCustomProps } from './utils';

src-docs/src/services/playground/knobs.js

@@ -214,6 +214,7 @@ const Knob = ({
               isInvalid={error && error.length > 0}
               compressed
               fullWidth
+              hasNoInitialSelection={!valueKey && !defaultValue}
             />
           </EuiFormRow>
         );
@@ -241,11 +242,11 @@ const Knob = ({
                 <EuiSwitch
                   id={name}
                   label={custom.label || ''}
-                  checked={typeof val !== 'undefined' && val}
+                  checked={typeof val !== 'undefined' && Boolean(val)}
                   onChange={(e) => {
                     const value = e.target.checked;
 
-                    set(value ? value : undefined);
+                    set(value ? custom.value ?? e.target.checked : undefined);
                   }}
                   compressed
                 />

src-docs/src/services/playground/playground.js

@@ -26,7 +26,15 @@ export default ({ config, setGhostBackground, playgroundClassName }) => {
       newCode = newCode.replace(/(\);)$/m, '');
     }
 
-    return format(newCode.trim(), ' '.repeat(4));
+    let formatted;
+    // TODO: Replace `html-format` with something better.
+    // Notably, something more jsx-friendly
+    try {
+      formatted = format(newCode.trim(), ' '.repeat(4));
+    } catch {
+      formatted = newCode.trim();
+    }
+    return formatted;
   };
 
   const Playground = () => {

src-docs/src/services/playground/utils.js

@@ -0,0 +1,16 @@
+import template from '@babel/template';
+
+export const generateAst = (value) => {
+  return template.ast(String(value), { plugins: ['jsx'] }).expression;
+};
+
+export const generateCustomProps = (props) => {
+  return props.reduce((obj, item) => {
+    return {
+      ...obj,
+      [item]: {
+        generate: generateAst,
+      },
+    };
+  }, {});
+};

src-docs/src/views/icon/logos.js

@@ -20,7 +20,7 @@ import {
   EuiCopy,
 } from '../../../../src/components';
 
-const iconTypes = [
+export const iconTypes = [
   'logoAppSearch',
   'logoBeats',
   'logoBusinessAnalytics',

src-docs/src/views/page/page.js

@@ -8,7 +8,6 @@ import {
   EuiPageContentHeader,
   EuiPageContentHeaderSection,
   EuiPageHeader,
-  EuiPageHeaderSection,
   EuiPageSideBar,
   EuiTitle,
 } from '../../../../src/components';
@@ -17,14 +16,7 @@ export default () => (
   <EuiPage>
     <EuiPageSideBar>SideBar nav</EuiPageSideBar>
     <EuiPageBody component="div">
-      <EuiPageHeader>
-        <EuiPageHeaderSection>
-          <EuiTitle size="l">
-            <h1>Page title</h1>
-          </EuiTitle>
-        </EuiPageHeaderSection>
-        <EuiPageHeaderSection>Page abilities</EuiPageHeaderSection>
-      </EuiPageHeader>
+      <EuiPageHeader pageTitle="Page title" />
       <EuiPageContent>
         <EuiPageContentHeader>
           <EuiPageContentHeaderSection>

src-docs/src/views/page/page_content_center_with_side_bar.js

@@ -8,7 +8,6 @@ import {
   EuiPageContentHeader,
   EuiPageContentHeaderSection,
   EuiPageHeader,
-  EuiPageHeaderSection,
   EuiPageSideBar,
   EuiTitle,
 } from '../../../../src/components';
@@ -18,14 +17,11 @@ export default () => (
     <EuiPageSideBar>SideBar nav</EuiPageSideBar>
     {/* The EUI docs site  already has a wrapping <main> tag, so we've changed this example to a <div> for accessibility. You likely don't need to copy the `component` prop for your own usage. */}
     <EuiPageBody component="div">
-      <EuiPageHeader>
-        <EuiPageHeaderSection>
-          <EuiTitle size="l">
-            <h1>Page title</h1>
-          </EuiTitle>
-        </EuiPageHeaderSection>
-        <EuiPageHeaderSection>Page abilities</EuiPageHeaderSection>
-      </EuiPageHeader>
+      <EuiPageHeader
+        pageTitle="Page title"
+        rightSideContent={['Page abilities']}
+        alignItems="center"
+      />
       <EuiPageContent verticalPosition="center" horizontalPosition="center">
         <EuiPageContentHeader>
           <EuiPageContentHeaderSection>

src-docs/src/views/page/page_example.js

@@ -3,6 +3,7 @@ import React from 'react';
 import { renderToHtml } from '../../services';
 
 import { GuideSectionTypes } from '../../components';
+import Playground from './playground';
 
 import {
   EuiCode,
@@ -27,6 +28,18 @@ import PageSimple from './page_simple';
 const pageSimpleSource = require('!!raw-loader!./page_simple');
 const pageSimpleHtml = renderToHtml(PageSimple);
 
+import PageHeader from './page_header';
+const pageHeaderSource = require('!!raw-loader!./page_header');
+const pageHeaderHtml = renderToHtml(PageHeader);
+
+import PageHeaderTabs from './page_header_tabs';
+const pageHeaderTabsSource = require('!!raw-loader!./page_header_tabs');
+const pageHeaderTabsHtml = renderToHtml(PageHeaderTabs);
+
+import PageHeaderCustom from './page_header_custom';
+const pageHeaderCustomSource = require('!!raw-loader!./page_header_custom');
+const pageHeaderCustomHtml = renderToHtml(PageHeaderCustom);
+
 import PageContentOnly from './page_content_only';
 const pageContentOnlySource = require('!!raw-loader!./page_content_only');
 const pageContentOnlyHtml = renderToHtml(Page);
@@ -40,6 +53,7 @@ const PageContentCenterWithSideBarSource = require('!!raw-loader!./page_content_
 const PageContentCenterWithSideBarHtml = renderToHtml(Page);
 
 export const PageExample = {
+  playground: Playground,
   title: 'Page',
   intro: (
     <EuiText>
@@ -117,6 +131,136 @@ export const PageExample = {
         </div>
       ),
     },
+    {
+      title: 'Page header',
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: pageHeaderSource,
+        },
+        {
+          type: GuideSectionTypes.HTML,
+          code: pageHeaderHtml,
+        },
+      ],
+      text: (
+        <>
+          <p>
+            <strong>EuiPageHeader</strong> comes with some pre-determined
+            content that you can apply to the left and right sides of the
+            component.
+          </p>
+          <p>
+            The left side allows you to pass any combination of{' '}
+            <EuiCode>pageTitle</EuiCode>, <EuiCode>description</EuiCode>,{' '}
+            <EuiCode>tabs</EuiCode>, or any <EuiCode>children</EuiCode>. The
+            order of which are determined by the particular combination.
+          </p>
+          <p>
+            The right side, <EuiCode>rightSideContent</EuiCode>, allows for just
+            a simple <strong>array of nodes</strong> which are placed within a
+            flexbox row. This is usually in the form of multiple buttons, of
+            which, at least one is primary (or{' '}
+            <EuiCode language="ts">{'fill="true"'}</EuiCode>). These items are
+            also displayed in <strong>reverse order</strong> so that the first
+            and primary action will be displayed far right.
+          </p>
+          <p>
+            You can further adjust the display of these content types with an
+            optional <EuiCode>iconType</EuiCode> placed to the left of the
+            title, <EuiCode>alignItems</EuiCode> for adjusting the vertical
+            alignment of the two sides, and <EuiCode>responsiveOrder</EuiCode>
+            to determine which content side to display first on smaller screens.
+          </p>
+        </>
+      ),
+      demo: (
+        <div className="guideDemo__highlightLayout--single">
+          <PageHeader />
+        </div>
+      ),
+      props: { EuiPageHeader },
+      snippet: `<EuiPageHeader
+  pageTitle="Page title"
+  tabs={[
+    { label:"Tab 1" , isSelected: true },
+    { label:"Tab 2" }
+  ]}
+  description="Example of a description."
+  rightSideContent={[
+    <EuiButton fill>Button 1</EuiButton>,
+    <EuiButton>Button 2</EuiButton>
+  ]}
+/>`,
+    },
+    {
+      title: 'Page header tabs',
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: pageHeaderTabsSource,
+        },
+        {
+          type: GuideSectionTypes.HTML,
+          code: pageHeaderTabsHtml,
+        },
+      ],
+      text: (
+        <>
+          <p>
+            When using supplying <EuiCode>tabs</EuiCode> without a{' '}
+            <EuiCode>pageTitle</EuiCode>, <strong>EuiPageHeader</strong> will
+            promote those tabs as if they are the page title. This means that
+            any <EuiCode>description</EuiCode>, or <EuiCode>children</EuiCode>{' '}
+            will sit <strong>below</strong> the tabs.
+          </p>
+        </>
+      ),
+      demo: (
+        <div className="guideDemo__highlightLayout--single">
+          <PageHeaderTabs />
+        </div>
+      ),
+      props: { EuiPageHeader },
+      snippet: `<EuiPageHeader
+  tabs={[
+    { label:"Tab 1" , isSelected: true },
+    { label:"Tab 2" }
+  ]}
+  description="Example of a description."
+/>`,
+    },
+    {
+      title: 'Page header custom',
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: pageHeaderCustomSource,
+        },
+        {
+          type: GuideSectionTypes.HTML,
+          code: pageHeaderCustomHtml,
+        },
+      ],
+      text: (
+        <>
+          <p>
+            The page header content props mainly are helpful props to push
+            content into established Elastic page layout patterns. They are
+            completely optional and by nature, inflexible. If you need a layout
+            that does not match these patterns you can simply pass in your own{' '}
+            <EuiCode>children</EuiCode> utilizing the{' '}
+            <strong>EuiPageHeaderSection</strong> components.
+          </p>
+        </>
+      ),
+      demo: (
+        <div className="guideDemo__highlightLayout">
+          <PageHeaderCustom />
+        </div>
+      ),
+      props: { EuiPageHeader },
+    },
     {
       title: 'Page with content only',
       source: [